Agents

This page covers the full lifecycle of a platform-level agent: registration, plugin management, durable state, and workspace snapshots.

Base URL: https://api.ainative.studio

Agent Registration

Register a Platform Agent

POST /api/v1/public/agents/register

Register a new platform-level agent. Returns a stable agent_id and a one-time api_key — store the key immediately, it cannot be retrieved again.

No authentication required.

Request body

Field	Type	Required	Description
`agent_name`	string	Yes	Human-readable label (1–128 chars)
`capabilities`	string[]	Yes	Capability slugs the agent claims (e.g. `"memory"`, `"search"`)
`callback_url`	string	Yes	HTTPS URL the platform will POST events to

curl -X POST https://api.ainative.studio/api/v1/public/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "security-scanner",
    "capabilities": ["vulnerability_scan", "code_review"],
    "callback_url": "https://my-system.example.com/webhooks/agent"
  }'

import httpx

resp = httpx.post(
    "https://api.ainative.studio/api/v1/public/agents/register",
    json={
        "agent_name": "security-scanner",
        "capabilities": ["vulnerability_scan", "code_review"],
        "callback_url": "https://my-system.example.com/webhooks/agent",
    },
)
data = resp.json()
agent_id = data["agent_id"]
api_key = data["api_key"]  # Store this — it will not be shown again

Response

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "api_key": "pa_Xk3mN9p..."
}

Field	Description
`agent_id`	Stable UUID for the agent
`api_key`	Bearer token prefixed `pa_`. Shown once — store securely.

Plugins

Plugins are capability packages installed from the platform registry onto a specific agent. Each agent has its own isolated plugin list.

Path prefix: /api/v1/agents/{agent_id}/plugins

Install a Plugin

POST /api/v1/agents/{agent_id}/plugins

Install a plugin from the registry onto the agent. The agent must exist and have ACTIVE status. Installing the same plugin twice returns 409 Conflict.

Auth required

Path param	Description
`agent_id`	The target agent's ID

Request body

Field	Type	Required	Description
`plugin_id`	string	Yes	Plugin ID from the registry

curl -X POST https://api.ainative.studio/api/v1/agents/550e8400-e29b-41d4-a716-446655440001/plugins \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "web-search-v2"}'

import httpx

resp = httpx.post(
    "https://api.ainative.studio/api/v1/agents/{agent_id}/plugins",
    headers={"Authorization": "Bearer <your_api_key>"},
    json={"plugin_id": "web-search-v2"},
)
print(resp.json())

Response 201 Created

{
  "id": "inst-3f8a12bc4d90",
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "plugin_id": "web-search-v2",
  "plugin_name": "Web Search",
  "plugin_version": "2.1.0",
  "plugin_description": "Real-time web search with snippet extraction",
  "tools": [
    {"name": "search_web", "description": "Search the web for a query"}
  ],
  "installed_by": "user-uuid",
  "installed_at": "2026-04-25T10:00:00Z"
}

List Installed Plugins

GET /api/v1/agents/{agent_id}/plugins

List all plugins installed on a specific agent, including metadata from the plugin registry.

Auth required

curl https://api.ainative.studio/api/v1/agents/{agent_id}/plugins \
  -H "Authorization: Bearer <your_api_key>"

Response

{
  "plugins": [
    {
      "id": "inst-3f8a12bc4d90",
      "agent_id": "550e8400-e29b-41d4-a716-446655440001",
      "plugin_id": "web-search-v2",
      "plugin_name": "Web Search",
      "plugin_version": "2.1.0",
      "tools": [...],
      "installed_by": "user-uuid",
      "installed_at": "2026-04-25T10:00:00Z"
    }
  ],
  "total": 1
}

Uninstall a Plugin

DELETE /api/v1/agents/{agent_id}/plugins/{plugin_id}

Remove a plugin from an agent. Decrements the plugin's install count in the registry.

Auth required

Returns 204 No Content on success, 404 if the plugin is not installed.

curl -X DELETE \
  https://api.ainative.studio/api/v1/agents/{agent_id}/plugins/web-search-v2 \
  -H "Authorization: Bearer <your_api_key>"

Durable State

Each agent has isolated, ZeroDB-backed NoSQL tables. State persists between agent invocations and survives process restarts.

Path prefix: /api/v1/cloud/agents/{agent_id}

Default storage limit: MAX_AGENT_STORAGE_BYTES (see /state/info for current value).

Query Agent State

POST /api/v1/cloud/agents/{agent_id}/sqlite/execute

Query rows from an agent's durable state table with optional key-value filters.

Request body

Field	Type	Default	Description
`table_name`	string	`"default"`	Table name within agent namespace (max 128 chars)
`filter`	object	null	MongoDB-style key-value filter on row data
`limit`	integer	100	Max rows to return (1–1000)
`offset`	integer	0	Pagination offset

curl -X POST \
  https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/sqlite/execute \
  -H "Content-Type: application/json" \
  -d '{
    "table_name": "session_cache",
    "filter": {"status": "active"},
    "limit": 50
  }'

Response

{
  "status": "success",
  "rows": [
    {"id": "row-1", "status": "active", "data": {...}}
  ],
  "total": 1
}

Get State Info

GET /api/v1/cloud/agents/{agent_id}/sqlite/info

Get table list, row counts, and storage usage for an agent's durable state.

curl https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/sqlite/info

Response

{
  "status": "success",
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "tables": ["default", "session_cache"],
  "table_count": 2,
  "size_bytes": 204800,
  "max_size_bytes": 10485760,
  "usage_percent": 1.95,
  "total_rows": 312
}

Destroy Agent State

DELETE /api/v1/cloud/agents/{agent_id}/sqlite

Permanently delete all ZeroDB tables and rows for an agent. This action is irreversible.

curl -X DELETE \
  https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/sqlite

Get Storage Usage Breakdown

GET /api/v1/cloud/agents/{agent_id}/state/usage

Detailed breakdown by storage category: KV store, NoSQL tables, memory records, and snapshots.

Set State TTL

PUT /api/v1/cloud/agents/{agent_id}/state/ttl

Configure how long durable state is retained before garbage collection. Default is 30 days.

Request body

Field	Type	Description
`ttl_days`	integer	TTL in days (1–365)

curl -X PUT \
  https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/state/ttl \
  -H "Content-Type: application/json" \
  -d '{"ttl_days": 90}'

List Expiring Agents

GET /api/v1/cloud/state/expiring

List agents whose durable state will expire within the next 7 days. Useful for monitoring dashboards.

Trigger Garbage Collection

POST /api/v1/cloud/state/gc

Immediately delete all expired agent state (KV stores, tables, memory records, snapshots past their TTL).

Workspace Snapshots

Snapshots are atomic, point-in-time captures of all agent state. Use them for checkpointing, rollback, and forking agents into parallel branches.

Create Snapshot

POST /api/v1/cloud/agents/{agent_id}/snapshot

Captures memory, KV store, NoSQL database, and conversation history atomically.

Request body (optional)

Field	Type	Description
`label`	string	Human-readable label (max 255 chars)
`metadata`	object	Arbitrary key-value metadata

curl -X POST \
  https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/snapshot \
  -H "Content-Type: application/json" \
  -d '{"label": "pre-refactor-checkpoint", "metadata": {"branch": "feature/auth"}}'

Response

{
  "status": "success",
  "snapshot_id": "snap-abc123",
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "label": "pre-refactor-checkpoint",
  "created_at": "2026-04-25T10:00:00Z"
}

Restore from Snapshot

POST /api/v1/cloud/agents/{agent_id}/restore/{snapshot_id}

Restore all agent state from a snapshot. Current state is overwritten.

curl -X POST \
  https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/restore/snap-abc123

Fork Agent from Snapshot

POST /api/v1/cloud/agents/{agent_id}/fork/{snapshot_id}

Create a new agent with a full copy of state from an existing snapshot. Useful for running parallel experiments.

Request body

Field	Type	Description
`new_agent_id`	string	ID for the forked agent (1–255 chars)

curl -X POST \
  https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/fork/snap-abc123 \
  -H "Content-Type: application/json" \
  -d '{"new_agent_id": "security-scanner-fork-1"}'

List Snapshots

GET /api/v1/cloud/agents/{agent_id}/snapshots

List available snapshots with pagination.

Query parameters

Param	Default	Description
`limit`	20	Max snapshots to return (1–100)
`offset`	0	Pagination offset

curl "https://api.ainative.studio/api/v1/cloud/agents/{agent_id}/snapshots?limit=10"

Trust Scores

Trust scores quantify agent reliability on a 0–100 scale using three sub-dimensions: reliability, responsiveness, and compliance.

Get Trust Score

GET /api/v1/agents/{agent_id}/trust

Auth required

curl https://api.ainative.studio/api/v1/agents/{agent_id}/trust \
  -H "Authorization: Bearer <your_api_key>"

Response

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "score": 87,
  "reliability": 92,
  "responsiveness": 85,
  "compliance": 84
}

Trust Leaderboard

GET /api/v1/agents/trust/leaderboard

Top N active agents ranked by trust score.

Query parameters

Param	Default	Description
`limit`	50	Max agents to return (1–100)

Trust History

GET /api/v1/agents/{agent_id}/trust/history

Daily trust score history for an agent.

Query parameters

Param	Default	Description
`days`	30	History window in days (1–365)

Trust Distribution

GET /api/v1/agents/trust/distribution

Platform-wide distribution of trust scores across 10 decile buckets.

Trust Recommendations

GET /api/v1/agents/{agent_id}/trust/recommendations

Actionable tips to improve an agent's trust score.

MCP Trust Gate

Control which agents are allowed to use an MCP server instance by enforcing a minimum trust score.

Set Trust Gate

PUT /api/v1/mcp/instances/{instance_id}/trust-gate

Set the minimum trust score required to access an MCP server. Only the instance owner can set the gate.

Request body

Field	Type	Description
`min_trust_score`	integer	Minimum score (0–100)

curl -X PUT \
  https://api.ainative.studio/api/v1/mcp/instances/{instance_id}/trust-gate \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"min_trust_score": 75}'

Get Trust Gate

GET /api/v1/mcp/instances/{instance_id}/trust-gate

Get the current trust threshold configuration for an MCP server instance.

Response

{
  "instance_id": "mcp-instance-uuid",
  "min_trust_score": 75,
  "has_gate": true
}

Agent Registration​

Register a Platform Agent​

Plugins​

Install a Plugin​

List Installed Plugins​

Uninstall a Plugin​

Durable State​

Query Agent State​

Get State Info​

Destroy Agent State​

Get Storage Usage Breakdown​

Set State TTL​

List Expiring Agents​

Trigger Garbage Collection​

Workspace Snapshots​

Create Snapshot​

Restore from Snapshot​

Fork Agent from Snapshot​

List Snapshots​

Trust Scores​

Get Trust Score​

Trust Leaderboard​

Trust History​

Trust Distribution​

Trust Recommendations​

MCP Trust Gate​

Set Trust Gate​

Get Trust Gate​

Agent Registration

Register a Platform Agent

Plugins

Install a Plugin

List Installed Plugins

Uninstall a Plugin

Durable State

Query Agent State

Get State Info

Destroy Agent State

Get Storage Usage Breakdown

Set State TTL

List Expiring Agents

Trigger Garbage Collection

Workspace Snapshots

Create Snapshot

Restore from Snapshot

Fork Agent from Snapshot

List Snapshots

Trust Scores

Get Trust Score

Trust Leaderboard

Trust History

Trust Distribution

Trust Recommendations

MCP Trust Gate

Set Trust Gate

Get Trust Gate