List Notifications
curl --request GET \
--url https://api.example.com/v1/tools/notificationsimport requests
url = "https://api.example.com/v1/tools/notifications"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/v1/tools/notifications', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/tools/notifications",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/tools/notifications"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/v1/tools/notifications")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/tools/notifications")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"notifications": [
{
"id": "<string>",
"agentId": "<string>",
"type": "<string>",
"title": "<string>",
"body": "<string>",
"metadata": {},
"read": true,
"createdAt": "<string>"
}
],
"count": 123
}Notifications
List Notifications
List notifications for the authenticated agent
GET
/
v1
/
tools
/
notifications
List Notifications
curl --request GET \
--url https://api.example.com/v1/tools/notificationsimport requests
url = "https://api.example.com/v1/tools/notifications"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/v1/tools/notifications', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/tools/notifications",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/tools/notifications"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/v1/tools/notifications")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/tools/notifications")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"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
RequiresX-Agent-ID header with the agent’s wallet address.
Reads return private, per-agent data, so they are protected by a signed read proof (x-agent-proof header) proving you control that wallet. The OneShot SDK signs and sends this automatically (TypeScript ≥ 0.25.0, Python ≥ 0.17.0). This is rolling out in log-only mode — requests without the proof still succeed today and will be rejected once enforcement is enabled; raw HTTP callers should start sending it. See Read Proof Authentication.
Query Parameters
boolean
default:"false"
If
true, only return unread notificationsnumber
default:"50"
Maximum number of notifications to return (max: 100)
Response
array
Array of notification objects
Show Notification object
Show Notification object
string
Unique notification ID (UUID)
string
Agent ID this notification belongs to
string
Notification type:
job_completed, job_failed, voice_completed, sms_completed, credit_issued, domain_expiring, phone_expiring, budget_warning, budget_exceededstring
Short notification title
string
Optional detailed message
object
Additional context (jobId, tool, amounts, etc.)
boolean
Whether the notification has been read
string
ISO timestamp when notification was created
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
| Type | Description |
|---|---|
job_completed | A job finished successfully |
job_failed | A job failed with an error |
voice_completed | Voice call completed (includes success evaluation) |
sms_completed | SMS batch delivery completed |
credit_issued | Credit was issued to your account |
domain_expiring | Domain will be released due to inactivity |
phone_expiring | Phone number will be released due to inactivity |
budget_warning | Spend crossed alert_at of the daily budget |
budget_exceeded | A paid call was blocked by the spend budget |