Menu
Sign In Pricing Add Podcast

Notifications API

The Notifications API allows you to create and manage search term notifications. Get notified via webhooks or email when new podcast transcriptions match your specified search terms.

Create Notification

Create a new notification for a search term.

bash
POST /api/notifications
$ 
curl -X POST "https://www.audioscrape.com/api/notifications" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "search_term": "\"artificial intelligence\" AND (ethics OR regulation) NOT military",
       "webhook_url": "https://your-webhook.com/endpoint",
       "email_recipient": "[email protected]"
     }'
Response:
{
  "id": 123,
  "search_term": "\"artificial intelligence\" AND (ethics OR regulation) NOT military",
  "webhook_url": "https://your-webhook.com/endpoint",
  "email_recipient": "[email protected]",
  "created_at": "2024-01-15T10:00:00Z",
  "delivery_stats": {
    "total_deliveries": 0,
    "successful_deliveries": 0,
    "failed_deliveries": 0,
    "last_delivery": null
  }
}

Parameters

Parameter Type Description
search_term string The term to search for in new transcriptions (supports advanced query syntax)
webhook_url string Optional URL to receive webhook notifications (must be HTTPS)
email_recipient string Optional email address to receive notifications

Advanced Query Syntax

Create precise notifications using our advanced query syntax:

Syntax Description Example
"phrase" Exact phrase matching "generative ai" - only get notified about exact matches
AND Both terms must be present blockchain AND security - require both terms
OR Either term can be present metaverse OR "web3" - get notified about either topic
NOT or - Excludes content with the term crypto NOT bitcoin - crypto mentions excluding bitcoin
term* Wildcard matching (prefix search) sustain* - matches sustainable, sustainability, etc.
( ) Grouping for complex queries (privacy OR security) AND healthcare - logical grouping

Notification Tip

Using precise queries reduces noise in your notifications. For example, "clean energy" AND innovation NOT "fossil fuels" will notify you only about innovative clean energy discussions that don't mention fossil fuels.

List Notifications

Retrieve all notifications for the authenticated user.

bash
GET /api/notifications
$ 
curl "https://www.audioscrape.com/api/notifications" \
     -H "Authorization: Bearer YOUR_API_KEY"
Response:
[
  {
    "id": 123,
    "search_term": "\"artificial intelligence\" AND (ethics OR regulation) NOT military",
    "webhook_url": "https://your-webhook.com/endpoint",
    "email_recipient": "[email protected]",
    "created_at": "2024-01-15T10:00:00Z",
    "delivery_stats": {
      "total_deliveries": 5,
      "successful_deliveries": 4,
      "failed_deliveries": 1,
      "last_delivery": "2024-01-16T15:30:00Z"
    }
  },
  {
    "id": 124,
    "search_term": "climate* AND (solution OR innovation)",
    "webhook_url": null,
    "email_recipient": "[email protected]",
    "created_at": "2024-01-20T14:25:00Z",
    "delivery_stats": {
      "total_deliveries": 2,
      "successful_deliveries": 2,
      "failed_deliveries": 0,
      "last_delivery": "2024-01-23T09:15:00Z"
    }
  }
]

Delete Notification

Delete a specific notification.

bash
DELETE /api/notifications/:id
$ 
curl -X DELETE "https://www.audioscrape.com/api/notifications/123" \
     -H "Authorization: Bearer YOUR_API_KEY"
Response:
204 No Content

Webhook Payload

When a notification is triggered, your webhook will receive a POST request with the following payload: 

{
  "notification_id": 123,
  "episode_id": 456,
  "segment_id": "125.4",
  "podcast_title": "Future Tech Today",
  "episode_title": "Ethics in AI Development",
  "text": "The regulatory framework for artificial intelligence ethics is still being developed across most jurisdictions.",
  "segment_url": "https://www.audioscrape.com/podcast/future-tech-today/episode/ethics-in-ai-development/segment/125.4"
}

Your webhook endpoint should return a 2XX status code to acknowledge receipt.

Email Notifications

Email notifications include the matching text, source information, and a direct link to the segment in the podcast.

Sample Email Subject:

New Match in Podcast: Future Tech Today

Sample Email Body:

New Match Found in "Future Tech Today"

A new transcription segment matching your search term has been found in:

  • Podcast: Future Tech Today
  • Episode: Ethics in AI Development

Matching Text:

The regulatory framework for artificial intelligence ethics is still being developed across most jurisdictions.

View this segment

Delivery Statistics

The delivery_stats object provides information about notification deliveries:

Field Type Description
total_deliveries integer Total number of delivery attempts
successful_deliveries integer Number of successful deliveries
failed_deliveries integer Number of failed deliveries
last_delivery string Timestamp of the most recent delivery attempt

Usage Note

The notification frequency depends on your subscription plan. Check the pricing page for details on notification limits.