Skip to main content
GET
/
v1
/
tools
/
notifications
List Notifications
curl --request GET \
  --url https://api.example.com/v1/tools/notifications
{
  "notifications": [
    {
      "id": "<string>",
      "agentId": "<string>",
      "type": "<string>",
      "title": "<string>",
      "body": "<string>",
      "metadata": {},
      "read": true,
      "createdAt": "<string>"
    }
  ],
  "count": 123
}

​
Overview

Returns a list of notifications for the agent. Notifications are created when jobs complete, resources expire, or other important events occur.

​
Authentication

Requires X-Agent-ID header with the agent’s wallet address.

​
Query Parameters

​
unread
boolean
default:"false"
If true, only return unread notifications
​
limit
number
default:"50"
Maximum number of notifications to return (max: 100)

​
Response

​
notifications
array
Array of notification objects
​
count
number
Number of notifications returned

​
Example Request

curl -X GET "https://win.oneshotagent.com/v1/tools/notifications?unread=true&limit=10" \
  -H "X-Agent-ID: 0xYourWalletAddress"

​
Example Response

{
  "notifications": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "agentId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "voice_completed",
      "title": "Voice call completed - Objective achieved",
      "body": "Successfully made dinner reservation for 2 at 7pm",
      "metadata": {
        "jobId": "job_abc123",
        "targetNumber": "+14155551234",
        "durationSeconds": 120,
        "successEvaluation": "pass"
      },
      "read": false,
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "agentId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "domain_expiring",
      "title": "domain myagent.com expiring",
      "body": "Will be released on 2024-02-01 due to inactivity",
      "metadata": {
        "resourceType": "domain",
        "resourceName": "myagent.com",
        "removalDate": "2024-02-01T00:00:00Z"
      },
      "read": false,
      "createdAt": "2024-01-10T08:00:00Z"
    }
  ],
  "count": 2
}

​
SDK Usage

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

// Get all notifications
const all = await agent.notifications();
console.log(`You have ${all.count} notifications`);

// Get only unread
const unread = await agent.notifications({ unread: true, limit: 10 });
for (const n of unread.notifications) {
  console.log(`[${n.type}] ${n.title}`);
}

​
Notification Types

TypeDescription
job_completedA job finished successfully
job_failedA job failed with an error
voice_completedVoice call completed (includes success evaluation)
sms_completedSMS batch delivery completed
credit_issuedCredit was issued to your account
domain_expiringDomain will be released due to inactivity
phone_expiringPhone number will be released due to inactivity