aevatar Station APIs

aevatar Station APIs （V1）#

Dev/Staging

https://auth-station-staging.aevatar.ai

Production

https://auth-station.aevatar.ai

1. Authentication#

Endpoint: /connect/token

Application Login#

grant_type

string

Yes

Authorization method, default: client_credentials

scope

string

Yes

Scope of permissions, e.g., Aevatar

client_id

string

Yes

Client ID (issued by backend)

client_secret

string

Yes

Client secret (issued by backend)

Portkey SDK Login#

grant_type

string

Yes

Authorization method, default: signature

public_key

string

Yes

Public key

signature

string

Yes

Digital signature

plain_text

string

Yes

Plaintext containing timestamp for validation

ca_hash

string

No

CA hash

chain_id

string

Yes

Chain ID

source

string

Yes

Source (portkey, nightElf)

client_id

string

Yes

Fixed value: AevatarAuthServer

2. Agent APIs#

2.1 Create New Agent#

POST /api/agent

Creates a new agent with specified configuration properties.

Request:

{
    "agentType": "AI Basic",
    "name": "Agent Name",
    "properties": {
        "a": "xx",
        "b": "yy",
        "c": 1
    }
}

Response:

{
    "code": "20000",
    "data": {
        "id": "d2ba5534-f602-4288-b2a3-ef033877a0c8",
        "agentType": "AIBasic",
        "name": "Agent Name",
        "GrainId": "xxx",
        "properties": {
            "a": "xx",
            "b": "yy",
            "c": 1
        }
    },
    "message": ""
}

2.2 Get Agent Details#

GET /api/agent/{id}

Request: None

Response:

{
    "code": "20000",
    "data": {
        "id": "guid",
        "name": "Agent Name",
        "agentType": "AIBasic",
        "GrainId": "xxx",
        "properties": {
            "a": "xx",
            "b": "yy",
            "c": 1
        }
    }
}

2.3 Update Agent Configuration#

PUT /api/agent/{id}

Updates the Atomic-Agent configuration. Note: properties must be updated in full.

Request:

{
    "name": "Updated Agent Name",
    "properties": {
        "a": "mm",
        "b": "nn",
        "c": 2
    }
}

Response:

{
    "code": "20000",
    "data": {
        "id": "d2ba5534-f602-4288-b2a3-ef033877a0c8",
        "agentType": "AI Basic",
        "name": "Updated Agent Name",
        "GrainId": "xxx",
        "properties": {
            "a": "mm",
            "b": "nn",
            "c": 2
        }
    },
    "message": ""
}

2.4 Delete Agent#

DELETE /api/agent/{id}

Response:

{
    "code": "20000",
    "data": {},
    "message": ""
}

2.5 Add Sub-agents#

POST /api/agent/{guid}/add-subagent

Request:

{
    "subAgents": ["guid1", "guid2"]
}

Response:

{
    "code": "20000",
    "data": {
        "subAgents": ["guid", "guid"]
    },
    "message": ""
}

2.6 Remove Sub-agents#

POST /api/agent/{id}/remove-subagent

Request:

{
    "removedSubAgents": ["guid1", "guid2"]
}

Response:

{
    "code": "20000",
    "data": {
        "subAgents": ["guid", "guid"] // remaining agents
    },
    "message": ""
}

2.7 Remove All Sub-agents#

POST /api/agent/{id}/remove-all-subagent

Request: None

Response:

{
    "code": "20000",
    "data": {},
    "message": ""
}

2.8 Query Agent Relationships#

GET /api/agent/{id}/relationship

Request: None

Response:

{
    "code": "20000",
    "data": {
        "parentAgent": "guid", // parent node id
        "subAgents": [
            "guid",
            "guid"
        ]
    }
}

2.9 Get All Business Agents and Initialization Parameters#

GET /api/agent/all-agents

Response:

{
    "code": "20000",
    "data": [
        {
            "agentType": "MarketLeaderGAgent",
            "agentParams": null
        },
        {
            "agentType": "InvestmentGAgent",
            "agentParams": [
                {
                    "name": "InvestmentContent",
                    "type": "System.String"
                },
                {
                    "name": "Number",
                    "type": "System.Int32"
                }
            ]
        }
    ],
    "message": ""
}

2.10 Publish Events#

POST /api/agent/publish

Request:

{
    "agentId": "2463cbd5-71bc-4292-ad82-0cf31bb91de6",
    "eventType": "InvestmentEvent",
    "eventProperties": {
        "Content": "abc"
    }
}

Response:

{
    "code": "20001",
    "data": {},
    "message": "empty result"
}

Subscription Event APIs#

3.1 Get Available Event Types#

GET /api/subscription/events/{id}

Response:

{
    "code": "20000",
    "data": [
        {
            "eventType": "InvestmentEvent",
            "description": "No description available",
            "eventProperties": [
                {
                    "name": "ResponseContent",
                    "type": "System.String",
                    "description": "ResponseContent"
                },
                {
                    "name": "Content",
                    "type": "System.String",
                    "description": "Unique identifier for the target chat where the message will be sent."
                }
            ]
        },
        {
            "eventType": "SendMessageEvent",
            "description": "No description available",
            "eventProperties": [
                {
                    "name": "ChatId",
                    "type": "System.String",
                    "description": "Unique identifier for the target chat where the message will be sent."
                },
                {
                    "name": "Message",
                    "type": "System.String",
                    "description": "Text content of the message to be sent."
                },
                {
                    "name": "Photo",
                    "type": "System.String",
                    "description": "File path or URL of the photo to be sent with the message."
                },
                {
                    "name": "Caption",
                    "type": "System.String",
                    "description": "Optional caption for the photo, if provided."
                },
                {
                    "name": "ReplyMessageId",
                    "type": "System.String",
                    "description": "Optional ID of the message to which this message is a reply."
                },
                {
                    "name": "BotName",
                    "type": "System.String",
                    "description": "The name of the bot."
                }
            ]
        }
    ],
    "message": ""
}

3.2 Subscribe to Events#

POST /api/subscription

Subscribe to one or more events and provide a callback URL for event notifications.

Request:

{
    "AgentId": "xxxxx-xxxx-xxxx",
    "eventTypes": ["UserCreated", "OrderCompleted"], // empty array for all events
    "callbackUrl": "https://subscriber.example.com/webhook"
}

Response:

{
  "code": "20000",
  "data": {
      "subscriptionId": "sub-123",
      "subscriberId": "subscriber-123",
      "eventTypes": ["UserCreated", "OrderCompleted"],
      "callbackUrl": "https://subscriber.example.com/webhook"
      },
  "message": ""
    
}

3.3 Cancel Event Subscription#

DELETE /api/{subscriptionId}

Cancels a specific subscription using the SubscriptionId.

Response:

{
   "code": "20000",
   "data": {},
   "message": ""
}

3.4 Receive Event Push#

Events are pushed to the subscriber's callback URL via HTTP POST.

Example push request:

POST https://subscriber.example.com/webhook
Content-Type: application/json
Authorization: Bearer {TOKEN}

{
    "AgentId": "PumpFun",
    "eventId": "evt-789",
    "eventType": "UserCreated",
    "timestamp": "2023-10-21T12:00:00Z",
    "Atomicgent": {
        "id": 1,
        "name": "Agent Name",
        "type": "AI Basic"
    },
    "payload": {
        "UserId": 12345,
        "UserName": "Alice",
        "Email": "[email protected]"
    },
    "metadata": {
        "traceId": "trace-12345",
        "correlationId": "correlation-67890"
    }
}

Subscriber must return HTTP 2XX to indicate successful receipt.

3.5 Query Subscription Status#

GET /api/subscription/{subscriptionId}

Response:

{
    "subscriptionId": "xxx-xxx-xxx",
    "agentId": "xxx-xxx-xxxx",
    "eventTypes": ["UserCreated", "OrderCompleted"],
    "callbackUrl": "https://subscriber.example.com/webhook",
    "status": "active",
    "createdAt": "2023-10-21T10:30:00Z"
}

#

4. Query Agent State and Event Logs#

4.1 Query State#

GET /api/query/state

Query Parameters:

  • stateName (string, required): Type name of the agent state (e.g., twittergagentstate)
  • id (string, required): Agent ID

    • Response:

    {
    "code": "20000",
    "data": {
        "state": {
            "content": "[\"hhh\"]",
            "number": 0,
            "children": "[]",
            "cTime": "2025-02-13T11:24:32.281744Z"
        }
    },
    "message": ""
}

    Note:

  • The state object in the data field represents the requested agent's state
  • The children and cTime fields are internal fields and can be ignored
  • Other fields are custom fields defined for that state

    • 4.2 Query Event Logs#

    GET /api/query/logs

    Query Parameters:

  • agentType (string, optional): Agent type
  • id (string, optional): Agent ID
  • pageIndex (int, optional): Page number, defaults to 0
  • pageSize (int, optional): Page size, defaults to 20

    • Response:

    {
    "code": "20000",
    "data": {
        "items": [
            {
                "id": "7cf24974-17ae-4666-bdc7-81cd1f5f12bd",
                "agentPrimaryKey": "462ef9eb-60e5-466f-a5db-0186cd48a408",
                "agentGrainType": "Aevatar.Application.Grains.Agents.Investment/InvestmentGAgent",
                "eventName": "InitializationGEvent",
                "ctime": "2025-02-13T08:56:46.43786Z",
                "eventJson": "{\"Content\":\"hhh\",\"Id\":\"7cf24974-17ae-4666-bdc7-81cd1f5f12bd\",\"Ctime\":\"2025-02-13T08:56:46.437857Z\"}"
            }
        ],
        "totalCount": 1
    },
    "message": ""
}

    Response Fields:

  • items: Array of event log objects
  • totalCount: Total number of log entries

    • Edited on: 21 February 2025 07:27:44 GMT+0