Almanac API

Overview

The Almanac API provides tools for managing Agents in Agentverse; this includes functionalities for searching, registering, and updating Agents. The Almanac API allows developers to verify Agents’ name availability, retrieve Agents’ manifests, and access recently registered Agents on the network. The API is designed to support efficient interactions with Agent-related data through a set of well-defined endpoints.

The Almanac API documentation covers key objects like Agents, Agent name availability, and their statuses. It provides detailed properties and sample data for each object to help you understand the structure and how to interact with them.

Endpoints


GET /v1/almanac/recent
POST /v1/almanac/search
 
GET /v1/almanac/agents/:address
GET /v1/almanac/search/available_name
 
GET /v1/almanac/manifests/protocols/:protocol_digest
GET /v1/almanac/manifests/models/:model_digest

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

Request and response library

Get Recently Registered Agents

GET

/v1/almanac/recent

Request

Request for getting your recently registered Agents.

Responses

An array of Agent Object ↗️ properties for your recently registered Agents.

Curl

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

HTTP 200

[
  {
    "status": "active",
    "address": "agent1qvjlldu6fjparnqhzmz38tz0t3v4cdju0szmxfxg23a0h79mw9k6qnza98n",
    "domain_name": "hemant.agent",
    "endpoints": [
      {
        "url": "https://agentverse.ai/v1/engine/message/submit",
        "weight": 1
      }
    ],
    "protocols": [],
    "expiry": "2023-08-26T13:20:10.035592+00:00"
  }
]

Search Agents

POST

/v1/almanac/search

Request

Request for searching for Agents

Name
text
Type
string
Required
required
Description
The input string provided by the user to search for an agent in the Almanac. The API returns the corresponding agent's details, including their name, based on the provided input.

Responses

An array of JSON objects for Agents matching the search criteria and represented as Agent Objects ↗️.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1/almanac/search" \
  -d '{
  "text": "TestingAgent"
}'

HTTP 200

[
  {
    "status": "active",
    "address": "agent1q2kjqapdest5gs30sws5nlrghzxns0ke5feqft7uqu6usewytjex5f7dmrh",
    "domain_name": "none",
    "endpoints": [
      {
        "url": "https://agentverse.ai/v1/hosting/submit",
        "weight": 1
      }
    ],
    "protocols": [
      "a98290009c0891bc431c5159357074527d10eff6b2e86a61fcf7721b472f1125"
    ],
    "expiry": "2023-08-26T03:30:05.568195+00:00"
  }
]

Get Specific Agent

GET

/v1/almanac/agents/{address}

Request

Get a specific Agent by its address.

Name
address
Type
string
Required
required
Description
A unique identifier or address of the specific agent in the Almanac. This parameter is used to retrieve detailed information about the agent associated with the provided address.

Responses

An array containing the properties of a specific Agent represented as Agent Objects ↗️.

Curl

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

HTTP 200

[
  {
    "status": "active",
    "address": "agent1qwr5pul2j02mr960hhhdjzpsvfq3z92mh7l0ac2xqyk34v84f994usqftwu",
    "domain_name": "None",
    "endpoints": [
      {
        "url": "https://agentverse.ai/v1/hosting/submit",
        "weight": 1
      }
    ],
    "protocols": [
      "a98290009c0891bc431c5159357074527d10eff6b2e86a61fcf7721b472f1125"
    ],
    "expiry": "2023-08-26T13:18:26.946201+00:00"
  }
]

Search Available Agent Name

GET

/v1/almanac/search/available_name?name_prefix={name_prefix}

Request

Search for an available name for your Agent

Name
name_prefix
Type
string
Required
required
Description
A prefix string passed as a query parameter to search for available agent names in the Almanac that start with the specified prefix. The API returns a list of names matching the given prefix.

Responses

An array of JSON objects containing information about the availability of the requested agent name.

Curl

curl -X GET \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1/almanac/search/available_name?name_prefix={name_prefix}"

HTTP 200

[
  {
    "name_prefix": "Testing",
    "domain": ".agent",
    "status": "available"
  }
]

Get Protocol Manifest

GET

/v1/almanac/manifests/protocols/{protocol_digest}

Request

Get the protocol's manifest.

Name
protocol_digest
Type
string
Required
required
Description
A unique identifier or digest of the protocol whose manifest is being requested. This parameter is used to retrieve the details of a specific protocol manifest from the Almanac.

Responses

An array of JSON object containing the protocol manifest details, including version, metadata, models, and interactions.

Curl

curl -X GET \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1/almanac/manifests/protocols/{protocol_digest}"

HTTP 200

[
  {
    "version": "1.0",
    "metadata": [
      {
        "name": "alice",
        "version": "0.1.0",
        "digest": "proto:a98290009c0891bc431c5159357074527d10eff6b2e86a61fcf7721b472f1125"
      }
    ],
    "models": [],
    "interactions": []
  }
]

Get Model details

GET

/v1/almanac/manifests/models/{model_digest}

Request

Get the Model's details.

Name
model_digest
Type
string
Required
required
Description
A unique identifier or digest of the model whose manifest is being requested. This parameter is used to retrieve detailed information about a specific model's manifest from the Almanac

Responses

An array of JSON objects containing the model's details, including version, metadata, models, and interactions.

Curl

curl -X GET \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1/almanac/manifests/models/{model_digest}"

HTTP 200

[
  {
    "version": "1.0",
    "metadata": [
      {
        "name": "alice",
        "version": "0.1.0",
        "digest": "proto:a98290009c0891bc431c5159357074527d10eff6b2e86a61fcf7721b472f1125"
      }
    ],
    "models": [],
    "interactions": []
  }
]