diff --git a/api-reference/agents.mdx b/api-reference/agents.mdx
index b8a27fe..d472150 100644
--- a/api-reference/agents.mdx
+++ b/api-reference/agents.mdx
@@ -51,17 +51,20 @@ Requires authentication and ownership of the agent.
```json
{
- "id": "agent_123",
- "status": "active",
- "startedAt": "2026-03-01T00:00:00Z",
- "plan": "starter",
- "subdomain": "agent_123.agents.localhost",
- "url": "https://agent_123.agents.localhost",
- "openclawVersion": "2026.3.13",
- "verified": false,
- "verificationType": null,
- "attestationUid": null,
- "verifiedAt": null
+ "agent": {
+ "id": "agent_123",
+ "status": "active",
+ "startedAt": "2026-03-01T00:00:00Z",
+ "plan": "starter",
+ "subdomain": "agent_123.agents.localhost",
+ "url": "https://agent_123.agents.localhost",
+ "openclawVersion": "2026.3.13",
+ "verified": false,
+ "verificationType": null,
+ "attestationUid": null,
+ "verifiedAt": null
+ },
+ "status": "ok"
}
```
@@ -172,19 +175,158 @@ Requires session authentication.
## Get agent configuration
-`GET /api/agents/:id/config` is deprecated. This endpoint is not currently implemented and may be removed in a future release.
+```http
+GET /api/agents/:id/config
+```
+
+Returns the configuration for an agent. Requires authentication and ownership.
+
+### Response
+
+```json
+{
+ "config": {
+ "model": "claude-opus-4-6",
+ "channels": ["telegram"],
+ "skills": []
+ },
+ "status": "ok"
+}
+```
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 404 | Agent not found or not owned by user |
+| 500 | Failed to fetch agent configuration |
## Update agent configuration
-`PUT /api/agents/:id/config` is deprecated. This endpoint is not currently implemented and may be removed in a future release.
+```http
+PUT /api/agents/:id/config
+```
+
+Updates the configuration for an agent. Requires authentication and ownership. The request body is forwarded to the backend configuration service.
+
+### Request body
+
+Pass the configuration fields you want to update. The exact fields depend on the backend configuration schema.
+
+### Response
+
+```json
+{
+ "config": {
+ "model": "claude-opus-4-6",
+ "channels": ["telegram", "discord"],
+ "skills": ["browser"]
+ },
+ "status": "updated"
+}
+```
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 404 | Agent not found or not owned by user |
+| 500 | Failed to update agent configuration |
## Get agent logs
-`GET /api/agents/:id/logs` is deprecated. This endpoint is not currently implemented and may be removed in a future release.
+```http
+GET /api/agents/:id/logs
+```
+
+Returns activity logs for an agent. Requires authentication and ownership.
+
+### Query parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `limit` | number | `50` | Maximum number of log entries to return (capped at 100) |
+| `level` | string | — | Filter by log level. Options: `info`, `warning`, `error`, `debug`. Returns all levels when omitted. |
+
+### Response
+
+```json
+{
+ "logs": [
+ {
+ "id": "log-0",
+ "timestamp": "2026-03-19T12:00:00Z",
+ "level": "info",
+ "message": "Agent activity log entry 1",
+ "source": "agent",
+ "agentId": "agent_123"
+ }
+ ],
+ "total": 50,
+ "limit": 50,
+ "status": "ok"
+}
+```
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 401 | Unauthorized |
+| 404 | Agent not found or not owned by user |
+| 500 | Failed to fetch logs |
## Get agent messages
-`GET /api/agents/:id/messages` is deprecated. This endpoint is not currently implemented and may be removed in a future release.
+```http
+GET /api/agents/:id/messages
+```
+
+Returns messages exchanged with an agent. Requires authentication and ownership.
+
+### Query parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `limit` | number | `50` | Maximum number of messages to return (capped at 100) |
+| `offset` | number | `0` | Number of messages to skip for pagination |
+
+### Response
+
+```json
+{
+ "messages": [
+ {
+ "id": "msg-0",
+ "agentId": "agent_123",
+ "sender": "user",
+ "content": "User message 1",
+ "timestamp": "2026-03-19T12:00:00Z",
+ "platform": "telegram"
+ },
+ {
+ "id": "msg-1",
+ "agentId": "agent_123",
+ "sender": "agent",
+ "content": "Agent response to message 0",
+ "timestamp": "2026-03-19T11:59:00Z",
+ "platform": "discord"
+ }
+ ],
+ "total": 50,
+ "limit": 50,
+ "offset": 0,
+ "status": "ok"
+}
+```
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 401 | Unauthorized |
+| 404 | Agent not found or not owned by user |
+| 500 | Failed to fetch messages |
## Get agent stats
@@ -428,8 +570,7 @@ GET /api/agents/:id/verification
"verificationType": null,
"attestationUid": null,
"verifierAddress": null,
- "verifiedAt": null,
- "metadata": null
+ "verifiedAt": null
}
```
@@ -444,10 +585,9 @@ POST /api/agents/:id/verify
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `verificationType` | string | Yes | One of: `eas`, `coinbase`, `ens`, `webauthn` |
-| `verified` | boolean | No | Verification status flag |
| `attestationUid` | string | For `eas` | Attestation UID from EAS |
-| `verifierAddress` | string | No | Address of the verifying wallet |
-| `metadata` | object | No | Additional verification metadata |
+| `walletAddress` | string | Conditional | Wallet address of the verifier. Required for `ens` verification. |
+| `signature` | string | Conditional | Cryptographic signature. Required for `coinbase`, `ens`, and `webauthn` verification. |
#### Response
@@ -465,8 +605,9 @@ POST /api/agents/:id/verify
| Code | Description |
|------|-------------|
-| 400 | Invalid verification type or missing required fields |
+| 400 | Invalid verification type or missing required fields. Each type has specific requirements: `eas` requires `attestationUid`; `coinbase` and `webauthn` require `signature`; `ens` requires both `signature` and `walletAddress`. |
| 401 | Unauthorized |
+| 500 | Failed to process verification |
### Remove verification
diff --git a/api-reference/openapi.json b/api-reference/openapi.json
index da5326e..bdbe005 100644
--- a/api-reference/openapi.json
+++ b/api-reference/openapi.json
@@ -1,217 +1,1116 @@
{
"openapi": "3.1.0",
"info": {
- "title": "OpenAPI Plant Store",
- "description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification",
+ "title": "Agentbot API",
+ "description": "API for creating, managing, and interacting with AI agents on the Agentbot platform.",
+ "version": "1.0.0",
"license": {
"name": "MIT"
- },
- "version": "1.0.0"
+ }
},
"servers": [
{
- "url": "http://sandbox.mintlify.com"
+ "url": "https://agentbot.raveculture.xyz",
+ "description": "Production"
}
],
"security": [
{
- "bearerAuth": []
+ "sessionAuth": []
}
],
"paths": {
- "/plants": {
+ "/api/agents": {
+ "get": {
+ "summary": "List agents",
+ "description": "Returns all agents owned by the authenticated user. Returns an empty list when no session is present.",
+ "tags": ["Agents"],
+ "security": [
+ {},
+ { "sessionAuth": [] }
+ ],
+ "responses": {
+ "200": {
+ "description": "Agent list",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "agents": {
+ "type": "array",
+ "items": { "$ref": "#/components/schemas/Agent" }
+ },
+ "count": { "type": "integer" },
+ "status": { "type": "string", "example": "ok" }
+ }
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/Error" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/api/agents/{id}": {
+ "get": {
+ "summary": "Get agent",
+ "description": "Returns a single agent by ID. Requires authentication and ownership.",
+ "tags": ["Agents"],
+ "parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Agent details",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "agent": { "$ref": "#/components/schemas/AgentDetail" },
+ "status": { "type": "string", "example": "ok" }
+ }
+ }
+ }
+ }
+ },
+ "401": { "description": "Unauthorized" },
+ "404": { "description": "Agent not found or not owned by user" },
+ "500": { "description": "Failed to fetch agent" }
+ }
+ }
+ },
+ "/api/agents/{id}/config": {
"get": {
- "description": "Returns all plants from the system that the user has access to",
+ "summary": "Get agent configuration",
+ "description": "Returns the configuration for an agent. Requires authentication and ownership.",
+ "tags": ["Agents"],
"parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Agent configuration",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "config": { "type": "object" },
+ "status": { "type": "string", "example": "ok" }
+ }
+ }
+ }
+ }
+ },
+ "404": { "description": "Agent not found" },
+ "500": { "description": "Failed to fetch agent configuration" }
+ }
+ },
+ "put": {
+ "summary": "Update agent configuration",
+ "description": "Updates the configuration for an agent. Requires authentication and ownership.",
+ "tags": ["Agents"],
+ "parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ],
+ "requestBody": {
+ "description": "Configuration fields to update",
+ "content": {
+ "application/json": {
+ "schema": { "type": "object" }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Updated configuration",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "config": { "type": "object" },
+ "status": { "type": "string", "example": "updated" }
+ }
+ }
+ }
+ }
+ },
+ "404": { "description": "Agent not found" },
+ "500": { "description": "Failed to update agent configuration" }
+ }
+ }
+ },
+ "/api/agents/{id}/logs": {
+ "get": {
+ "summary": "Get agent logs",
+ "description": "Returns activity logs for an agent. Requires authentication and ownership.",
+ "tags": ["Agents"],
+ "parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "required": true,
+ "schema": { "type": "string" }
+ },
{
"name": "limit",
"in": "query",
- "description": "The maximum number of results to return",
- "schema": {
- "type": "integer",
- "format": "int32"
+ "description": "Maximum number of log entries (default 50, max 100)",
+ "schema": { "type": "integer", "default": 50 }
+ },
+ {
+ "name": "level",
+ "in": "query",
+ "description": "Filter by log level",
+ "schema": { "type": "string", "enum": ["info", "warning", "error", "debug"] }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Agent logs",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "logs": {
+ "type": "array",
+ "items": { "$ref": "#/components/schemas/LogEntry" }
+ },
+ "total": { "type": "integer" },
+ "limit": { "type": "integer" },
+ "status": { "type": "string", "example": "ok" }
+ }
+ }
+ }
}
+ },
+ "401": { "description": "Unauthorized" },
+ "404": { "description": "Agent not found" },
+ "500": { "description": "Failed to fetch logs" }
+ }
+ }
+ },
+ "/api/agents/{id}/messages": {
+ "get": {
+ "summary": "Get agent messages",
+ "description": "Returns messages exchanged with an agent. Requires authentication and ownership.",
+ "tags": ["Agents"],
+ "parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "required": true,
+ "schema": { "type": "string" }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "Maximum number of messages (default 50, max 100)",
+ "schema": { "type": "integer", "default": 50 }
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "Number of messages to skip",
+ "schema": { "type": "integer", "default": 0 }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Agent messages",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "messages": {
+ "type": "array",
+ "items": { "$ref": "#/components/schemas/Message" }
+ },
+ "total": { "type": "integer" },
+ "limit": { "type": "integer" },
+ "offset": { "type": "integer" },
+ "status": { "type": "string", "example": "ok" }
+ }
+ }
+ }
+ }
+ },
+ "401": { "description": "Unauthorized" },
+ "404": { "description": "Agent not found" },
+ "500": { "description": "Failed to fetch messages" }
+ }
+ }
+ },
+ "/api/agents/{id}/stats": {
+ "get": {
+ "summary": "Get agent stats",
+ "description": "Returns live container metrics when available, with a mock fallback.",
+ "tags": ["Agents"],
+ "parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "required": true,
+ "schema": { "type": "string" }
}
],
"responses": {
"200": {
- "description": "Plant response",
+ "description": "Agent statistics",
"content": {
"application/json": {
"schema": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/Plant"
+ "type": "object",
+ "properties": {
+ "stats": { "$ref": "#/components/schemas/AgentStats" },
+ "status": { "type": "string", "enum": ["ok", "mock"] }
}
}
}
}
},
- "400": {
- "description": "Unexpected error",
+ "401": { "description": "Unauthorized" },
+ "404": { "description": "Agent not found" },
+ "500": { "description": "Internal server error" }
+ }
+ }
+ },
+ "/api/agents/{id}/verify": {
+ "post": {
+ "summary": "Verify agent",
+ "description": "Submit a verification for an agent using EAS, Coinbase, ENS, or WebAuthn.",
+ "tags": ["Agents"],
+ "parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/VerifyRequest" }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Verification result",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "success": { "type": "boolean" },
+ "verified": { "type": "boolean" },
+ "verificationType": { "type": "string" },
+ "attestationUid": { "type": "string" },
+ "verifiedAt": { "type": "string", "format": "date-time" }
+ }
+ }
+ }
+ }
+ },
+ "400": { "description": "Invalid verification type or missing required fields" },
+ "401": { "description": "Unauthorized" },
+ "500": { "description": "Failed to process verification" }
+ }
+ },
+ "delete": {
+ "summary": "Remove verification",
+ "description": "Removes verification from an agent.",
+ "tags": ["Agents"],
+ "parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Verification removed",
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/Error"
+ "type": "object",
+ "properties": {
+ "success": { "type": "boolean", "example": true }
+ }
}
}
}
+ },
+ "401": { "description": "Unauthorized" },
+ "500": { "description": "Failed to remove verification" }
+ }
+ }
+ },
+ "/api/agents/provision": {
+ "post": {
+ "summary": "Provision agent",
+ "description": "Provisions a new agent. Requires an active subscription unless the caller is an admin.",
+ "tags": ["Agents"],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/ProvisionRequest" }
+ }
}
+ },
+ "responses": {
+ "201": {
+ "description": "Agent provisioned",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "success": { "type": "boolean" },
+ "agent": { "$ref": "#/components/schemas/Agent" }
+ }
+ }
+ }
+ }
+ },
+ "400": { "description": "Agent name is required" },
+ "401": { "description": "Unauthorized" },
+ "402": { "description": "Active subscription required" },
+ "429": { "description": "Agent limit reached for your plan" },
+ "500": { "description": "Failed to provision agent" }
}
},
+ "get": {
+ "summary": "List provisioned agents",
+ "description": "Lists agents provisioned by the authenticated user.",
+ "tags": ["Agents"],
+ "responses": {
+ "200": {
+ "description": "Agent list",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "success": { "type": "boolean" },
+ "agents": {
+ "type": "array",
+ "items": { "$ref": "#/components/schemas/Agent" }
+ },
+ "count": { "type": "integer" }
+ }
+ }
+ }
+ }
+ },
+ "401": { "description": "Unauthorized" },
+ "500": { "description": "Failed to list agents" }
+ }
+ }
+ },
+ "/api/v1/gateway": {
"post": {
- "description": "Creates a new plant in the store",
+ "summary": "Gateway",
+ "description": "Routes requests to registered plugins. Supports Stripe and MPP payment methods.",
+ "tags": ["Gateway"],
+ "parameters": [
+ {
+ "name": "X-Plugin-Id",
+ "in": "header",
+ "description": "Plugin to route the request to",
+ "schema": { "type": "string" }
+ },
+ {
+ "name": "X-Payment-Method",
+ "in": "header",
+ "description": "Payment method: stripe or mpp",
+ "schema": { "type": "string", "enum": ["stripe", "mpp"] }
+ }
+ ],
"requestBody": {
- "description": "Plant to add to the store",
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/NewPlant"
+ "type": "object",
+ "properties": {
+ "plugin": { "type": "string", "description": "Plugin ID" },
+ "messages": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "role": { "type": "string" },
+ "content": { "type": "string" }
+ }
+ }
+ }
+ }
}
}
- },
- "required": true
+ }
},
"responses": {
"200": {
- "description": "plant response",
+ "description": "Plugin response",
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/Plant"
+ "type": "object",
+ "properties": {
+ "plugin": { "type": "string" },
+ "message": { "type": "string" },
+ "timestamp": { "type": "string", "format": "date-time" },
+ "payment": {
+ "type": "object",
+ "properties": {
+ "method": { "type": "string" },
+ "receipt": { "type": "string", "nullable": true }
+ }
+ }
+ }
}
}
}
},
- "400": {
- "description": "unexpected error",
+ "401": { "description": "Unauthorized" },
+ "402": { "description": "Payment required (MPP challenge)" },
+ "500": { "description": "Internal server error" },
+ "502": { "description": "No plugin registered for the given ID" }
+ }
+ },
+ "options": {
+ "summary": "CORS preflight",
+ "description": "Returns CORS headers for the gateway endpoint.",
+ "tags": ["Gateway"],
+ "responses": {
+ "204": { "description": "No content" }
+ }
+ }
+ },
+ "/api/keys": {
+ "get": {
+ "summary": "List API keys",
+ "description": "Returns all API keys owned by the authenticated user.",
+ "tags": ["Keys"],
+ "responses": {
+ "200": {
+ "description": "Key list",
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/Error"
+ "type": "object",
+ "properties": {
+ "keys": {
+ "type": "array",
+ "items": { "$ref": "#/components/schemas/ApiKey" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "401": { "description": "Unauthorized" }
+ }
+ },
+ "post": {
+ "summary": "Create API key",
+ "description": "Creates a new API key. The raw key is only returned once.",
+ "tags": ["Keys"],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "required": ["name"],
+ "properties": {
+ "name": { "type": "string", "maxLength": 64 }
}
}
}
}
+ },
+ "responses": {
+ "201": {
+ "description": "Key created",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "id": { "type": "string" },
+ "name": { "type": "string" },
+ "key": { "type": "string" },
+ "createdAt": { "type": "string", "format": "date-time" }
+ }
+ }
+ }
+ }
+ },
+ "400": { "description": "Name required or too long" },
+ "401": { "description": "Unauthorized" },
+ "500": { "description": "Failed to create key" }
}
}
},
- "/plants/{id}": {
- "delete": {
- "description": "Deletes a single plant based on the ID supplied",
+ "/api/keys/{id}": {
+ "get": {
+ "summary": "Get API key",
+ "description": "Returns a single API key by ID.",
+ "tags": ["Keys"],
"parameters": [
{
"name": "id",
"in": "path",
- "description": "ID of plant to delete",
"required": true,
- "schema": {
- "type": "integer",
- "format": "int64"
+ "schema": { "type": "string" }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Key details",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/ApiKey" }
+ }
}
+ },
+ "401": { "description": "Unauthorized" },
+ "404": { "description": "Key not found" }
+ }
+ },
+ "delete": {
+ "summary": "Delete API key",
+ "description": "Deletes an API key by ID.",
+ "tags": ["Keys"],
+ "parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "required": true,
+ "schema": { "type": "string" }
}
],
"responses": {
- "204": {
- "description": "Plant deleted",
- "content": {}
+ "200": {
+ "description": "Key deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "success": { "type": "boolean", "example": true }
+ }
+ }
+ }
+ }
},
- "400": {
- "description": "unexpected error",
+ "401": { "description": "Unauthorized" },
+ "404": { "description": "Key not found" }
+ }
+ }
+ },
+ "/api/metrics": {
+ "get": {
+ "summary": "Platform metrics",
+ "description": "Returns platform-wide metrics. No authentication required.",
+ "tags": ["Metrics"],
+ "security": [],
+ "responses": {
+ "200": {
+ "description": "Platform metrics",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/PlatformMetrics" }
+ }
+ }
+ },
+ "500": { "description": "Failed to fetch metrics" }
+ }
+ }
+ },
+ "/api/health": {
+ "get": {
+ "summary": "Health check",
+ "description": "Returns platform health status. No authentication required.",
+ "tags": ["Health"],
+ "security": [],
+ "responses": {
+ "200": {
+ "description": "Health status",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HealthStatus" }
+ }
+ }
+ },
+ "500": { "description": "Health check failed" }
+ }
+ }
+ },
+ "/api/memory": {
+ "get": {
+ "summary": "Get agent memory",
+ "description": "Returns stored memory for an agent.",
+ "tags": ["Memory"],
+ "parameters": [
+ {
+ "name": "agentId",
+ "in": "query",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Agent memory",
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/Error"
+ "type": "object",
+ "properties": {
+ "memory": { "type": "object" },
+ "agentId": { "type": "string" },
+ "count": { "type": "integer" },
+ "lastUpdated": { "type": "string", "format": "date-time" }
+ }
+ }
+ }
+ }
+ },
+ "400": { "description": "agentId is required" },
+ "401": { "description": "Unauthorized" },
+ "404": { "description": "Agent not found" },
+ "500": { "description": "Failed to fetch memory" }
+ }
+ },
+ "post": {
+ "summary": "Save agent memory",
+ "description": "Saves memory data for an agent. Supports single key upsert or bulk upsert (max 50 keys, max 100KB per value).",
+ "tags": ["Memory"],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "required": ["memory", "agentId"],
+ "properties": {
+ "memory": { "type": "object" },
+ "agentId": { "type": "string" },
+ "key": { "type": "string" }
}
}
}
}
+ },
+ "responses": {
+ "200": {
+ "description": "Memory saved",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "success": { "type": "boolean" },
+ "agentId": { "type": "string" },
+ "saved": { "type": "integer" }
+ }
+ }
+ }
+ }
+ },
+ "400": { "description": "Invalid request" },
+ "401": { "description": "Unauthorized" },
+ "404": { "description": "Agent not found" },
+ "500": { "description": "Failed to save memory" }
}
}
- }
- },
- "webhooks": {
- "/plant/webhook": {
+ },
+ "/api/skills": {
+ "get": {
+ "summary": "List skills",
+ "description": "Returns available skills. Supports filtering by category and featured status.",
+ "tags": ["Skills"],
+ "security": [],
+ "parameters": [
+ {
+ "name": "category",
+ "in": "query",
+ "schema": { "type": "string" }
+ },
+ {
+ "name": "featured",
+ "in": "query",
+ "schema": { "type": "boolean" }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Skills list",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "skills": { "type": "array", "items": { "type": "object" } },
+ "categories": { "type": "array", "items": { "type": "string" } },
+ "featured": { "type": "array", "items": { "type": "object" } }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
"post": {
- "description": "Information about a new plant added to the store",
+ "summary": "Install skill",
+ "description": "Installs a skill on an agent.",
+ "tags": ["Skills"],
"requestBody": {
- "description": "Plant added to the store",
+ "required": true,
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/NewPlant"
+ "type": "object",
+ "required": ["skillId", "agentId"],
+ "properties": {
+ "skillId": { "type": "string" },
+ "agentId": { "type": "string" }
+ }
}
}
}
},
"responses": {
"200": {
- "description": "Return a 200 status to indicate that the data was received successfully"
+ "description": "Skill installed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "success": { "type": "boolean" }
+ }
+ }
+ }
+ }
+ },
+ "401": { "description": "Unauthorized" }
+ }
+ }
+ },
+ "/api/wallet": {
+ "get": {
+ "summary": "Get wallet",
+ "description": "Returns wallet information. When CDP is configured, returns CDP status without authentication.",
+ "tags": ["Wallet"],
+ "security": [
+ {},
+ { "sessionAuth": [] }
+ ],
+ "responses": {
+ "200": {
+ "description": "Wallet information",
+ "content": {
+ "application/json": {
+ "schema": {
+ "oneOf": [
+ { "$ref": "#/components/schemas/CdpWallet" },
+ { "$ref": "#/components/schemas/UserWallet" }
+ ]
+ }
+ }
+ }
+ },
+ "401": { "description": "Unauthorized" }
+ }
+ },
+ "post": {
+ "summary": "Wallet actions",
+ "description": "Perform wallet operations: create, get_seed, or export_seed.",
+ "tags": ["Wallet"],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "required": ["action"],
+ "properties": {
+ "action": { "type": "string", "enum": ["create", "get_seed", "export_seed"] }
+ }
+ }
+ }
}
+ },
+ "responses": {
+ "200": { "description": "Action result" },
+ "400": { "description": "Invalid action or wallet already exists" },
+ "401": { "description": "Unauthorized" },
+ "403": { "description": "Seed export disabled" },
+ "404": { "description": "No wallet found" }
}
}
}
},
"components": {
"schemas": {
- "Plant": {
- "required": [
- "name"
- ],
+ "Agent": {
+ "type": "object",
+ "properties": {
+ "id": { "type": "string" },
+ "name": { "type": "string" },
+ "model": { "type": "string" },
+ "status": { "type": "string" },
+ "websocketUrl": { "type": "string" },
+ "createdAt": { "type": "string", "format": "date-time" },
+ "updatedAt": { "type": "string", "format": "date-time" }
+ }
+ },
+ "AgentDetail": {
+ "type": "object",
+ "properties": {
+ "id": { "type": "string" },
+ "status": { "type": "string" },
+ "startedAt": { "type": "string", "format": "date-time" },
+ "plan": { "type": "string" },
+ "subdomain": { "type": "string" },
+ "url": { "type": "string" },
+ "openclawVersion": { "type": "string" },
+ "verified": { "type": "boolean" },
+ "verificationType": { "type": "string", "nullable": true },
+ "attestationUid": { "type": "string", "nullable": true },
+ "verifiedAt": { "type": "string", "format": "date-time", "nullable": true }
+ }
+ },
+ "AgentStats": {
+ "type": "object",
+ "properties": {
+ "agentId": { "type": "string" },
+ "cpu": { "type": "string" },
+ "memory": { "type": "string" },
+ "memoryPercent": { "type": "string" },
+ "network": { "type": "string" },
+ "uptime": { "type": "number" },
+ "uptimeFormatted": { "type": "string" },
+ "status": { "type": "string" },
+ "pids": { "type": "string" },
+ "messagesProcessed": {},
+ "messagesPerHour": {},
+ "averageResponseTime": {},
+ "successRate": {},
+ "errorRate": {}
+ }
+ },
+ "LogEntry": {
+ "type": "object",
+ "properties": {
+ "id": { "type": "string" },
+ "timestamp": { "type": "string", "format": "date-time" },
+ "level": { "type": "string", "enum": ["info", "warning", "error", "debug"] },
+ "message": { "type": "string" },
+ "source": { "type": "string" },
+ "agentId": { "type": "string" }
+ }
+ },
+ "Message": {
+ "type": "object",
+ "properties": {
+ "id": { "type": "string" },
+ "agentId": { "type": "string" },
+ "sender": { "type": "string", "enum": ["user", "agent"] },
+ "content": { "type": "string" },
+ "timestamp": { "type": "string", "format": "date-time" },
+ "platform": { "type": "string", "enum": ["telegram", "discord", "whatsapp"] }
+ }
+ },
+ "VerifyRequest": {
+ "type": "object",
+ "required": ["verificationType"],
+ "properties": {
+ "verificationType": { "type": "string", "enum": ["eas", "coinbase", "ens", "webauthn"] },
+ "attestationUid": { "type": "string", "description": "Required for eas verification" },
+ "walletAddress": { "type": "string", "description": "Required for ens verification" },
+ "signature": { "type": "string", "description": "Required for coinbase, ens, and webauthn verification" }
+ }
+ },
+ "ProvisionRequest": {
+ "type": "object",
+ "required": ["name"],
+ "properties": {
+ "name": { "type": "string" },
+ "model": { "type": "string", "default": "claude-opus-4-6" },
+ "config": { "type": "object" },
+ "tier": { "type": "string", "enum": ["starter", "pro", "enterprise"] }
+ }
+ },
+ "ApiKey": {
+ "type": "object",
+ "properties": {
+ "id": { "type": "string" },
+ "name": { "type": "string" },
+ "keyPreview": { "type": "string" },
+ "createdAt": { "type": "string", "format": "date-time" },
+ "lastUsed": { "type": "string", "format": "date-time", "nullable": true }
+ }
+ },
+ "PlatformMetrics": {
"type": "object",
"properties": {
- "name": {
- "description": "The name of the plant",
- "type": "string"
+ "metrics": {
+ "type": "object",
+ "properties": {
+ "agents": {
+ "type": "object",
+ "properties": {
+ "total": { "type": "integer" },
+ "active": { "type": "integer" },
+ "inactive": { "type": "integer" },
+ "failed": { "type": "integer" }
+ }
+ },
+ "messages": {
+ "type": "object",
+ "properties": {
+ "today": { "type": "integer" },
+ "thisWeek": { "type": "integer" },
+ "thisMonth": { "type": "integer" }
+ }
+ },
+ "deployments": {
+ "type": "object",
+ "properties": {
+ "total": { "type": "integer" },
+ "successful": { "type": "integer" },
+ "failed": { "type": "integer" }
+ }
+ },
+ "uptime": {
+ "type": "object",
+ "properties": {
+ "platformUptime": { "type": "number" },
+ "averageAgentUptime": { "type": "number" }
+ }
+ },
+ "performance": {
+ "type": "object",
+ "properties": {
+ "averageResponseTime": { "type": "number" },
+ "successRate": { "type": "string" },
+ "errorRate": { "type": "string" }
+ }
+ },
+ "storage": {
+ "type": "object",
+ "properties": {
+ "used": { "type": "number" },
+ "total": { "type": "number" },
+ "percentUsed": { "type": "number" }
+ }
+ }
+ }
},
- "tag": {
- "description": "Tag to specify the type",
- "type": "string"
- }
+ "timestamp": { "type": "string", "format": "date-time" },
+ "status": { "type": "string" }
}
},
- "NewPlant": {
- "allOf": [
- {
- "$ref": "#/components/schemas/Plant"
+ "HealthStatus": {
+ "type": "object",
+ "properties": {
+ "status": { "type": "string" },
+ "health": { "type": "string", "enum": ["healthy", "degraded", "unhealthy"] },
+ "timestamp": { "type": "string", "format": "date-time" },
+ "cpu": {
+ "type": "object",
+ "properties": {
+ "usage": { "type": "number" },
+ "cores": { "type": "integer" }
+ }
},
- {
- "required": [
- "id"
- ],
+ "memory": {
"type": "object",
"properties": {
- "id": {
- "description": "Identification number of the plant",
- "type": "integer",
- "format": "int64"
- }
+ "usage": { "type": "number" },
+ "total": { "type": "number" },
+ "used": { "type": "number" },
+ "free": { "type": "number" }
}
- }
- ]
+ },
+ "uptime": { "type": "number" }
+ }
},
- "Error": {
- "required": [
- "error",
- "message"
- ],
+ "CdpWallet": {
"type": "object",
"properties": {
- "error": {
- "type": "integer",
- "format": "int32"
+ "agenticWallet": {
+ "type": "object",
+ "properties": {
+ "status": { "type": "string" },
+ "projectId": { "type": "string" },
+ "features": { "type": "array", "items": { "type": "string" } }
+ }
},
- "message": {
- "type": "string"
- }
+ "instructions": { "type": "string" }
+ }
+ },
+ "UserWallet": {
+ "type": "object",
+ "properties": {
+ "address": { "type": "string", "nullable": true },
+ "balance": { "type": "string" },
+ "network": { "type": "string" },
+ "hasWallet": { "type": "boolean" },
+ "createdAt": { "type": "string", "format": "date-time" }
+ }
+ },
+ "Error": {
+ "type": "object",
+ "properties": {
+ "error": { "type": "string" }
}
}
},
"securitySchemes": {
- "bearerAuth": {
- "type": "http",
- "scheme": "bearer"
+ "sessionAuth": {
+ "type": "apiKey",
+ "in": "cookie",
+ "name": "next-auth.session-token",
+ "description": "NextAuth session cookie"
}
}
}
-}
\ No newline at end of file
+}