ConceptsConceptsGuidesGuidesExamplesExamplesReferencesReferencesAPIsAPIs
GitHub (opens in a new tab)
      • Almanac API
      • Hosting API
      • Mailroom API
      • Search API
      • AI Engine Chat API
      • Functions API
      • ASI Alliance Wallet APIs
      • Almanac API
      • Hosting API
        • Request and response library
      • Mailroom API
      • Search API
      • AI Engine Chat API
      • Functions API
      • ASI Alliance Wallet APIs
APIs
Agentverse
Hosting API

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 a list of all your Agents.

Responses

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

curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/agents
HTTP 200
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
    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

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

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

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

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

Look up Agent's code

Endpoint: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

curl -X GET
 -H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
 https://agentverse.ai/v1/hosting/agents/{agentAddress}/code
HTTP 200
HTTP 200
[
  {
    "digest": "4a8d510d546de8ff74aa27abaa7ebd95bf7876d8b31b265f6022c49d7b49cf45",
    "code": "Example code",
    "timestamp": "2023-08-22T12:49:45.856000+00:00"
  }
]

Update 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
    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

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
HTTP 200
[
  {
    "digest": "66089877730d0501a4ff1efedf545279d5db120d0960f1ea6a1c00f834ff9530"
  }
]

Start a specific Agent identified by its address

Endpoint: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

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

Endpoint: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

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

Endpoint: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

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

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

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

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

Endpoint: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

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

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
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 APIMailroom API

On This Page

  • Request and response library
  • Getting a list of your Agents
  • Creating a new Agent
  • Look up specific Agent
  • Delete Specified Agent
  • Look up Agent's code
  • Update code for a specific Agent
  • Start a specific Agent identified by its address
  • Stop a specific Agent identified by its address
  • Get the latest logs for an Agent
  • Delete the latest logs for an Agent
  • Get current Agent usage
  • Get Agent usage for a specific year and month
  • Get Current Agent Usage by Address
  • Get current Agent usage selected by address year and month
    • Edit this page on github (opens in a new tab)

Main website

Integrations

Events

We’re hiring!

Twitter (opens in a new tab)Telegram (opens in a new tab)Discord (opens in a new tab)GitHub (opens in a new tab)YouTube (opens in a new tab)LinkedIn (opens in a new tab)Reddit (opens in a new tab)
Sign up for developer updates