Hosting API

Welcome to the Hosting API documentation.

Overview

The hosting API allows you to manage your agents that are hosted by Agentverse. This involves creating new agents, updating the code of existing agents, starting and stopping agents, and getting logs of agents.

Endpoints
GET /v1/hosting/agents
POST /v1/hosting/agents
 
GET /v1/hosting/agents/:agentAddress
DELETE /v1/hosting/agents/:agentAddress
 
GET /v1/hosting/agents/:agentAddress/code
PUT /v1/hosting/agents/:agentAddress/code
 
POST /v1/hosting/agents/:agentAddress/start
POST /v1/hosting/agents/:agentAddress/stop
 
GET /v1/hosting/agents/:agentAddress/logs/latest
DELETE /v1/hosting/agents/:agentAddress/logs
 
GET /v1/hosting/usage/current
GET /v1/hosting/usage/:year/:month
 
GET /v1/hosting/usage/agents/:address/current
GET /v1/hosting/usage/agents/:address/:year/:month

Notable Objects

The Agent Object

Name
name
Type
string
Description
The given name of the agent. This is only a label that is used internally so users can keep track of their agents.
Name
address
Type
string
Description
The address of the agent. This is also the current public key of the agent.
Name
running
Type
boolean
Description
The current state of the agent. true if the agent is currently running, false otherwise.
Name
compiled
Type
boolean | null
Description
The current code compilation status for the agent. true if the agent is compiled, false if the compilation failed, null if the agent has not been compiled yet.
Name
revision
Type
integer
Description
The current revision of the agent. Everytime an update is made to the agent, the revision is incremented.
Name
code_digest
Type
string | null
Description
The current digest of the code of the agent. Useful for determining if there have been code changes that need to be applied to the agent.
This value can be null if the agent has not been compiled yet.
Name
wallet_address
Type
string | null
Description
The wallet address that is associated with the agent. If a wallet address is not associated with the agent, this value will be null.

Sample Agent Object
{
    "name": "My first agent",
    "address": "agent1q2dfhywtt8xazrdyzgap6gzdd7uhk4e0wmc3gjqt42esauaegcm8cuvclpj",
    "running": false,
    "compiled": true,
    "revision": 7,
    "code_digest": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "wallet_address": "fetch1dtwgzm6km4394erexa8ka05wva306wt9cc3mwk"
}

The AgentCode Object

Name
digest
Type
string
Description
Digest of the Agent's code.
Name
code
Type
string
Description
The Agent's code.
Name
timestamp
Type
string, date-time
Description
Timestamp of when the code was updated.

Sample AgentCode Object
{
    "digest": "66089877730d0501a4ff1efedf545279d5db120d0960f1ea6a1c00f834ff9530",
    "code": "alice = Agent(name="alice", seed="sample seed")",
    "timestamp": "2023-08-22T14:09:48.259000"
}

The AgentCodeDigest Object

Name
digest
Type
string
Description
Digest of the Agent's code.

Sample AgentCodeDigest Object
{
    "digest": "66089877730d0501a4ff1efedf545279d5db120d0960f1ea6a1c00f834ff9530"
}

The AgentLog Object

Name
log_timestamp
Type
string, date-time
Description
Timestamp of the log entry.
Name
log_entry
Type
string
Description
Log entry text.

Sample AgentLog Object
{
    "log_timestamp": "2023-08-22T14:09:48.259000", 
    "log_entry": "[INFO]: My count is: 0"
}

The NewAgent Object

Name
NewAgent
Type
string
Description
Name of the new Agent.

Sample NewAgent Object
{
    "name": "My first agent"
}

The UpdateAgentCode Object

Name
Code
Type
string
Description
The code for the new Agent.

Sample UpdateAgentCode Object
{
    "code": "alice = Agent(name="alice", seed="sample seed")"
}

Request and response library

Getting a list of your agents

Endpoint:GET/v1/hosting/agents

Request

Request for listing all of your agents at once

Curl


curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/agents

Responses

On a success the response will be an array of Agent Object properties.

HTTP 200

[
  {
    "name": "My first agent",
    "address": "agent1q2dfhywtt8xazrdyzgap6gzdd7uhk4e0wmc3gjqt42esauaegcm8cuvclpj",
    "running": false,
    "compiled": true,
    "revision": 7,
    "code_digest": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "wallet_address": "fetch1dtwgzm6km4394erexa8ka05wva306wt9cc3mwk"
  }
]

Creating a new agent

Endpoint:POST/v1/hosting/agents

Request

Request for creating a new agent

Name
name
Type
string
Description
The given name of the agent. This is only a label that is used internally so users can keep track of their agents.

Curl


curl -X POST
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/agents -d "{\"name\":\"My newest agent\"}"

Responses

On a success the response will be an array of Agent object properties.

HTTP 200

{
  "name": "My newest agent",
  "address": "agent1q2dfhywtt8xazrdyzgap6gzdd7uhk4e0wmc3gjqt42esauaegcm8cuvclpj",
  "running": false,
  "compiled": true,
  "revision": 1,
  "code_digest": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "wallet_address": "fetch1dtwgzm6km4394erexa8ka05wva306wt9cc3mwk"
}

Look up specific Agent

Endpoint:GET/v1/hosting/agents/{agentAddress}

Request

Looks up a specific agent by address on the hosting platform

Name
address
Type
string
Description
The address of the agent. This is also the current public key of the agent

Curl


curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/agents/{agentAddress}

Responses

On success, the response will be an array of the specified Agent's properties.

HTTP 200

[
  {
    "name": "InitialTest",
    "address": "agent1qtw0hy4kj65fv6j7qyv5mgdecq7c4qyqfqnjgc25wz4vf5h47l9l6m7qqtg",
    "domain": "None",
    "running": false,
    "compiled": null,
    "revision": 0,
    "code_digest": null,
    "wallet_address": "fetch1mh0zmyddgcvspz7ye5zdrzjcfjtz54cgafak67"
  }
]

Delete Specified Agent

Endpoint:DELETE/v1/hosting/agents/{agentAddress}

Request

Delete a specific agent, identified by address

Name
address
Type
string
Description
The address of the agent. This is also the current public key of the agent

Curl


curl -X DELETE
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/agents/{agentAddress}

Responses

On a success the response will be the deletion of the specified Agent from the platform

HTTP 200

{}

Look up Agent code

Endpoint:GET/v1/hosting/agents/{agentAddress}/code

Request

Looks up the code for an agent, specified by address.

Name
address
Type
string
Description
The address of the agent. This is also the current public key of the agent.

Curl


curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/agents/{agentAddress}/code

Responses

On success, the response will be an array of JSON objects containing the digest, code, and timestamp.

HTTP 200

[
  {
    "digest": "4a8d510d546de8ff74aa27abaa7ebd95bf7876d8b31b265f6022c49d7b49cf45",
    "code": "Example code",
    "timestamp": "2023-08-22T12:49:45.856000+00:00"
  }
]

Update Agent Code for a specific Agent

Endpoint:PUT/v1/hosting/agents/{agentAddress}/code

Request

Updates the code for a specific agent, identified by address.

Name
address
Type
string
Description
The address of the agent. This is also the current public key of the agent.
Name
code
Type
string
Description
The code for a specific agent on the Agentverse, provided as a collection of files. Each file includes an id, name, value (the code content), and language.

Curl


curl -X PUT
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/agents/{agentAddress}/code -d "{\"code\":[{\"id\":0,\"name\":\"agent.py\",\"value\":\"\\n# Congratulations on creating your first agent!\\n#\\n# This agent simply writes a greeting in the logs on a scheduled time interval.\\n#\\n# In this example we will use:\\n# - 'agent': this is your instance of the 'Agent' class that we will give an 'on_interval' task\\n# - 'ctx': this is the agent's 'Context', which gives you access to all the agent's important functions\\n\\n# A decorator (marked by the '@' symbol) just wraps the function defined under it in another function.\\n# This decorator tells your agent to run the function on a time interval with the specified 'period' in seconds.\\n# These functions must be 'async' because agents need to be able to perform many tasks concurrently.\\n@agent.on_interval(period=3.0)\\nasync def say_hello(ctx: Context):\\n    # ctx.logger is a standard Python logger that can log text with various levels of urgency\\n    # (exception, warning, info, debug). Here we will just use the 'info' level to write a greeting\\n    ctx.logger.info(f\\\"Hello, I'm an agent and my address is {agent.address}.\\\")\\n\",\"language\":\"python\"},{\"id\":1,\"name\":\".env\",\"value\":\"AGENT_SEED=YOUR_AGENT_SEED\",\"language\":\"python\"}]}"

Responses

On success, the response will be a JSON object with the updated digest.

HTTP 200

[
  {
    "digest": "66089877730d0501a4ff1efedf545279d5db120d0960f1ea6a1c00f834ff9530"
  }
]

Start a specific agent, identified by address.

Endpoint:POST/v1/hosting/agents/{address}/start

Request

Starts a specific agent, identified by address

Name
address
Type
string
Description
The address of the agent. This is also the current public key of the agent.

Curl


curl -X POST
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/agents/{address}/start

Responses

On success, the agent selected by address will start, and the API will return an array with the Agent's properties.

HTTP 200

[
  {
    "name": "InitialTest",
    "address": "agent1qvnppqyhk4hu0q64tnfkspux8hpd9zayyclhafvkz5340uqx3ax02txfll7",
    "domain": "None",
    "running": "True",
    "compiled": "False",
    "revision": "4",
    "code_digest": "66089877730d0501a4ff1efedf545279d5db120d0960f1ea6a1c00f834ff9530",
    "wallet_address": "None"
  }
]

Stop a specific agent, identified by address.

Endpoint:POST/v1/hosting/agents/{address}/stop

Request

Stops a specific agent, identified by address

Name
address
Type
string
Description
The address of the agent. This is also the current public key of the agent.

Curl


curl -X POST
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/agents/{address}/stop

Responses

On success, the agent selected by address will stop, and the API will return an array with the Agent's properties.

HTTP 200

[
  {
    "name": "InitialTest",
    "address": "agent1qvnppqyhk4hu0q64tnfkspux8hpd9zayyclhafvkz5340uqx3ax02txfll7",
    "domain": "None",
    "running": "False",
    "compiled": "False",
    "revision": "4",
    "code_digest": "66089877730d0501a4ff1efedf545279d5db120d0960f1ea6a1c00f834ff9530",
    "wallet_address": "None"
  }
]

Get Latest Logs For Agent

Endpoint:GET/v1/hosting/agents/{address}/logs/latest

Request

Get the latest logs for an Agent, identified by address

Name
address
Type
string
Description
The address of the agent. This is also the current public key of the agent.

Curl


curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/agents/{address}/logs/latest

Responses

On successful retrieval of the specified agent logs, the response will be an array of json objects containing the timestamp and log entry.

HTTP 200

[
  {
    "log_timestamp": "2023-08-22T14:09:48.259000",
    "log_entry": "[INFO]: My count is: 0"
  }
]

Delete the latest logs for an Agent

Endpoint:DELETE/v1/hosting/agents/{address}/logs

Request

Delete the latest logs for an Agent, identified by address

Name
address
Type
string
Description
The address of the agent. This is also the current public key of the agent.

Curl


curl -X DELETE
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/agents/{address}/logs

Responses

On success, the response will be the deletion of the specified agent logs.

HTTP 200

{}

Get current Agent usage

Endpoint:GET/v1/hosting/usage/current

Request

Get data about the usage of the currently selected Agent

Name
address
Type
string
Description
The address of the agent. This is also the current public key of the agent.

Curl


curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/usage/current -d "{\"address\":\"agent1qvnppqyhk4hu0q64tnfkspux8hpd9zayyclhafvkz5340uqx3ax02txfll7\"}"

Responses

On success, the response will be a json array with properties containing data about the usage of the currently selected agent.

HTTP 200

[
  {
    "year": "2023",
    "month": "8",
    "computation_time": "2291",
    "num_messages": "12",
    "num_message_bytes": "0",
    "num_agents": "4",
    "quota_computation_time": "3100000000",
    "quota_num_messages": "31000000",
    "quota_message_bytes": "63488000000",
    "quota_agents": "1000"
  }
]

Get Agent Usage for a specific year and month

Endpoint:GET/v1/hosting/usage/{year}/{month}

Request

Get data about the usage of the currently selected Agent for a selected year and month

Name
address
Type
string
Description

Curl


curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/usage/{year}/{month} -d "{\"address\":\"agent1qvnppqyhk4hu0q64tnfkspux8hpd9zayyclhafvkz5340uqx3ax02txfll7\"}"

Responses

On success, the response will be a json array with properties containing data about the usage of the currently selected Agent for a selected year and month.

HTTP 200

[
  {
    "year": "2023",
    "month": "8",
    "computation_time": "2291",
    "num_messages": "12",
    "num_message_bytes": "0",
    "num_agents": "4",
    "quota_computation_time": "3100000000",
    "quota_num_messages": "31000000",
    "quota_message_bytes": "63488000000",
    "quota_agents": "1000"
  }
]

Get Agent Usage for a specific year and month

Endpoint:GET/v1/hosting/usage/agents/{address}/current

Request

Get data about the usage for an Agent, identified by address

Name
address
Type
string
Description
The address of the agent. This is also the current public key of the agent.

Curl


curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/usage/agents/{address}/current

Responses

On success the response will be an array of json properties containing information about the current usage for a specified Agent identified by address.

HTTP 200

[
  {
    "year": "2023",
    "month": "8",
    "computation_time": "1230",
    "num_messages": "4",
    "num_message_bytes": "0"
  }
]

Get current Agent usage selected by address year and month

Endpoint:GET/v1/hosting/usage/agents/{address}/{year}/{month}

Request

Get data about the usage for an Agent, identified by address for a specific year and month

Name
address
Type
string
Description
The address of the agent. This is also the current public key of the agent.

Curl


curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/usage/agents/{address}/{year}/{month}

Responses

On success, the response will be a json array with properties for the specified Agent identified by address for a specific year and month

HTTP 200

[
  {
    "year": "2023",
    "month": "3",
    "computation_time": "1230",
    "num_messages": "4",
    "num_message_bytes": "0"
  }
]

Was this page helpful?

You can also leave detailed feedbackon Github

Almanac APIs Mailroom APIs