Skip to main content
POST
/
v1
/
agents
Register Agent
curl --request POST \
  --url https://api.truthlocks.com/v1/agents \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "agent_type": "orchestrator",
  "display_name": "Data Pipeline Orchestrator",
  "description": "Coordinates ETL pipeline agents",
  "scopes": [
    "datasets:read",
    "datasets:write",
    "models:read"
  ],
  "metadata": {
    "team": "data-engineering"
  }
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_type": "orchestrator",
  "display_name": "<string>",
  "description": "<string>",
  "status": "active",
  "scopes": [
    "<string>"
  ],
  "metadata": {},
  "trust_score": 0.5,
  "public_key": "<string>",
  "session_count": 123,
  "keys": [
    {
      "kid": "<string>",
      "algorithm": "<string>",
      "public_key": "<string>",
      "status": "active"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

​
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

​
agent_type
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.
​
display_name
string
required
Human-readable name for the agent. Used in dashboards, audit logs, and alert notifications. Maximum 256 characters.
​
description
string
Detailed description of the agent’s purpose, capabilities, or operational context. Maximum 2048 characters.
​
scopes
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.
​
metadata
object
Arbitrary key-value metadata attached to the agent. Useful for tagging, cost allocation, or integration-specific context. Maximum 16 KB serialized.
​
expires_at
string
ISO 8601 timestamp for automatic agent expiration. When reached, the agent transitions to revoked status. Omit for non-expiring agents.

​
Response

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

​
Example

curl -X POST https://api.truthlocks.com/v1/agents \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "llm",
    "display_name": "Customer Support Bot",
    "description": "Handles Tier-1 customer support inquiries via chat",
    "scopes": ["data:read", "tool:search.web", "!data:delete"],
    "metadata": {
      "team": "support",
      "model": "claude-3.5-sonnet",
      "environment": "production"
    }
  }'

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>