Hosting API

The Hosting API empowers users to manage their Agents on Agentverse. From creating and updating Agents to control their states and access detailed logs, this API offers comprehensive tools for efficient Agents management. Users can also retrieve usage statistics, monitor individual Agent performance, and ensure that their Agents operate as intended with up-to-date code.

This documentation provides an in-depth overview of available endpoints, notable objects, and practical examples, enabling developers to interact with the API effectively. Whether you're creating new Agents or managing existing ones, this guide will help you unlock the full potential of the Hosting API.

You can see our dedicated object reference documentation here .

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