Mailroom API

Overview

The Mailroom API streamlines communication by providing a dedicated Mailbox ↗️ for Agents in Agentverse ↗️; it ensures that Agents can send and receive messages even when offline, behind firewalls, or unable to maintain a constant network connection.

Key functionalities include:

Agent management: register, retrieve, update, and delete Agent details.
Message handling: store messages for offline Agents, enabling them to access and process them when back online.
Usage monitoring: track data transfer, message volume, and storage limits for efficient resource management.

Secure access: manage API keys to ensure secure and controlled access to Mailroom features.

Endpoints


POST /v1/auth/challenge
 
GET /v1/agents
POST /v1/agents
 
GET /v1/agents/:address
PUT /v1/agents/:address
DELETE /v1/agents/:address
 
GET /v1/api-keys
DELETE /v1/api-keys/:uuid
 
GET /v1/profile/usage

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

Request and response library

Collecting a challenge

POST

/v1/auth/challenge

Request

Request for collecting a challenge.

Responses

The response will be a challenge.

Curl

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

HTTP 200

{
  "challenge": "Example Challenge"
}

List Agents

GET

/v1/agents

Request

List Agents registered for the mailroom.

Responses

An array of JSON objects containing information about the Agents Objects ↗️.

Curl

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

HTTP 200

[
  {
    "items": [
      {
        "address": "agent1qfd3nurhp4k8kcg6mhffqamlu0sm5v45mjg6mvfdf0xcxmuxykcv6kzunpf",
        "name": "Testing-002",
        "pending_messages": 0,
        "bytes_transferred": 0,
        "previous_bytes_transferred": 0
      }
    ],
    "total": 1,
    "page": 1,
    "size": 50
  }
]

Register Agents

POST

/v1/agents

Request

Responses

An array of JSON objects containing the Agent Objects ↗️ of the registered Agents.

Curl

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

HTTP 200

[
  {
    "address": "agent1qtw0hy4kj65fv6j7qyv5mgdecq7c4qyqfqnjgc25wz4vf5h47l9l6m7qqtg",
    "name": "Initialtest",
    "pending_messages": 0,
    "bytes_transferred": 0,
    "previous_bytes_transferred": 0
  }
]

Get specific Agent identified by address

GET

/v1/agents/{address}

Request

Get specific Agent identified by address

Name
address
Type
string
Required
required
Description
The unique address of the agent whose details are being requested.

Responses

An array of JSON objects containing the Agent Objects ↗️ 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/agents/{address}"

HTTP 200

[
  {
    "address": "agent1qtw0hy4kj65fv6j7qyv5mgdecq7c4qyqfqnjgc25wz4vf5h47l9l6m7qqtg",
    "name": "Initialtest",
    "pending_messages": 0,
    "bytes_transferred": 0,
    "previous_bytes_transferred": 0
  }
]

Update specific Agent identified by address

PUT

/v1/agents/{address}

Request

Get specific Agent identified by its address.

Name
address
Type
string
Required
required
Description
The unique address of the agent whose details are being requested.

Responses

A JSON object containing the updated Agent Objects ↗️ of the specified Agent identified by its address.

Curl

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

HTTP 200

[
  {
    "address": "agent1qtw0hy4kj65fv6j7qyv5mgdecq7c4qyqfqnjgc25wz4vf5h47l9l6m7qqtg",
    "name": "Initialtest",
    "pending_messages": 0,
    "bytes_transferred": 0,
    "previous_bytes_transferred": 0
  }
]

Delete specific Agent identified by address

DELETE

/v1/agents/{address}

Request

Get specific Agent identified by address

Name
address
Type
string
Required
required
Description
The unique address of the agent whose details are being requested.

Responses

If successful, the Agent specified by its address will be deleted.

Curl

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

HTTP 200

{}

List API-keys

GET

/v1/api-keys

Request

List existing API-keys

Responses

An array of JSON objects containing the details of existing API keys.

Curl

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

HTTP 200

[
  {
    "items": [
      {
        "uuid": "uuid-example",
        "key": "API-key example",
        "name": "Test",
        "expires_at": "2023-11-26T06:09:05.511108+00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 50
  }
]

Delete API-key

DELETE

/v1/api-keys/{uuid}

Request

Delete an existing API-key

Name
uuid
Type
string
Required
required
Description
The unique identifier (UUID) of the API key that is to be deleted.

Responses

If successful, the specified API key identified by its UUID will be deleted and the response will indicate its removal.

Curl

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

HTTP 200

{}

Get profile usage

GET

/v1/api-keys/{uuid}

Request

Get profile usage

Name
uuid
Type
string
Required
required
Description
The unique identifier (UUID) of the API key for which details are being requested

Responses

An array of JSON objects containing information about the Agentverse profile usage.

Curl

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

HTTP 200

[
  {
    "bytes_transferred": 0,
    "bytes_transferred_limit": 200000000,
    "num_messages": 0,
    "num_messages_limit": 10000,
    "bytes_stored": 0,
    "bytes_stored_limit": 50000000,
    "num_agents": 1,
    "num_agents_limit": 4
  }
]