Hosting API

The Hosting API allows you to manage Agents on Agentverse, enabling tasks like creating, updating, starting, stopping, and monitoring Agents. It supports code updates, log retrieval, and usage tracking, ensuring efficient and scalable Agent operations. This documentation provides a complete guide to the API objects.

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

You can explore our dedicated objects reference documentation here ↗️.

Request and response library

Getting a list of your Agents

GET

/v1/hosting/agents

Request

Request a list of all your Agents.

Responses

An array of your Agents, each represented as an Agent Object ↗️.

Curl

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

HTTP 200

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

Creating a new Agent

POST

/v1/hosting/agents

Request

Request for creating a new Agent.

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

Responses

An array containing the properties of a newly created Agent represented as an Agent Object ↗️.

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"
}'

HTTP 200

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

Look up specific Agent

GET

/v1/hosting/agents/{agentAddress}

Request

Look up a specific Agent by its address on the hosting platform.

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

Responses

An array containing the properties of the specified Agent, represented as an Agent Object ↗️.

Curl

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

HTTP 200

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

Delete Specified Agent

DELETE

/v1/hosting/agents/{agentAddress}

Request

Delete a specific Agent identified by its address.

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

Responses

If successful, this will result in the deletion of the specified Agent from the Agentverse platform.

Curl

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

HTTP 200

{}

Look up Agent’s code

GET

/v1/hosting/agents/{agentAddress}/code

Request

Look up the code for an Agent specified by its address.

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

Responses

Retrieves the Agent's code details, including digest, code, and timestamp.

Curl

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

HTTP 200

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

Update code for a specific Agent

PUT

/v1/hosting/agents/{agentAddress}/code

Request

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

Name
address
Type
string
Required
required
Description
The address of the agent. This is also the current public key of the agent.
Name
code
Type
string
Required
required
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.

Responses

A JSON object containing the updated digest of the Agent's code.

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.\[email protected]_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"
    }
  ]
}'

HTTP 200

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

Start a specific Agent identified by its address

POST

/v1/hosting/agents/{address}/start

Request

Start a specific Agent identified by its address.

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

Responses

An array of JSON objects containing the properties of the started Agent identified by its address.

Curl

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

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 its address

POST

/v1/hosting/agents/{address}/stop

Request

Stops a specific Agent identified by address.

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

Responses

If successful, the selected Agent will stop, and the response will be an array with the Agent's properties.

Curl

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

HTTP 200

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

Get the latest logs for an Agent

GET

/v1/hosting/agents/{address}/logs/latest

Request

Get the latest logs for an Agent identified by address

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

Responses

An array of JSON objects containing the timestamp and log entry for a specific Agent identified by its address.

Curl

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

HTTP 200

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

Delete the latest logs for an Agent

DELETE

/v1/hosting/agents/{address}/logs

Request

Delete the latest logs for an Agent identified by address.

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

Responses

If successful, the response will be the deletion of the specified Agent's logs.

Curl

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

HTTP 200

{}

Get current Agent usage

GET

/v1/hosting/usage/current

Request

Get data about the usage of the currently selected Agent.

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

Responses

An array of JSON objects with properties containing data about the usage of the selected 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"
}'

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

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
Required
required
Description
The unique address of the agent for which the hosting usage data is requested.
Name
month
Type
string
Required
required
Description
The month for which the hosting usage data is requested.
Name
year
Type
string
Required
required
Description
The year for which the hosting usage data is requested.

Responses

An array of JSON objects for properties containing data about the usage of the selected Agent for a selected year and month.

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"
}'

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 Current Agent Usage by Address

GET

/v1/hosting/usage/agents/{address}/current

Request

Get data about the usage for an Agent identified by its address.

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

Responses

An array of JSON objects for properties containing information about the current usage for a specified Agent identified by its address.

Curl

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

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

GET

/v1/hosting/usage/agents/{address}/{year}/{month}

Request

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

Name
address
Type
string
Required
required
Description
The address of the agent. This is also the current public key of the agent.
Name
month
Type
string
Required
required
Description
The year for which the current agent usage data is requested.
Name
year
Type
string
Required
required
Description
The month for which the current agent hosting usage data is requested.

Responses

An array of JSON objects for properties of the specified Agent identified by its address for a specific year and month.

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}"

HTTP 200

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