Content Watcher Service

The Content Watcher Service monitors and retrieves the latest feed state, including content updates, reactions, and other user interactions on the Frequency network. It ensures that applications can stay up-to-date with the latest content and user activity.

API Reference

Open Full API Reference Page

Path Table

Reference Table

Path Details

[POST]/v1/scanner/reset

• Summary
  Reset blockchain scan to a specific block number or offset from the current position

RequestBody

• application/json

{
  // The block number to reset the scanner to
  blockNumber?: number
  // Number of blocks to rewind the scanner to (from `blockNumber` if supplied; else from latest block)
  rewindOffset?: number
  // Whether to schedule the new scan immediately or wait for the next scheduled interval
  immediate?: boolean
}

Responses

• 201

[GET]/v1/scanner/options

• Summary
  Get the current watch options for the blockchain content event scanner

Responses

• 200

application/json

{
  schemaIds?: number[]
  dsnpIds?: string[]
}

[POST]/v1/scanner/options

• Summary
  Set watch options to filter the blockchain content scanner by schemas or MSA Ids

RequestBody

• application/json

{
  schemaIds?: number[]
  dsnpIds?: string[]
}

Responses

• 201

[POST]/v1/scanner/pause

• Summary
  Pause the blockchain scanner

Responses

• 201

[POST]/v1/scanner/start

• Summary
  Resume the blockchain content event scanner

Parameters(Query)

immediate?: boolean

Responses

• 201

[POST]/v1/search

• Summary
  Search for DSNP content by id, start/end block, and filters

RequestBody

• application/json

{
  // An optional client-supplied reference ID by which it can identify the result of this search
  clientReferenceId?: string
  // The block number to search (backward) from
  startBlock?: number
  // The number of blocks to scan (backwards)
  blockCount: number
  // The schemaIds/dsnpIds to filter by
  filters?: #/components/schemas/ChainWatchOptionsDto
  // A webhook URL to be notified of the results of this search
  webhookUrl: string
}

Responses

• 200 Returns a jobId to be used to retrieve the results

application/json

{
  "type": "string"
}

[PUT]/v1/webhooks

• Summary
  Register a webhook to be called when new content is encountered on the chain

RequestBody

• application/json

{
  // Webhook URL
  url: string
  // Announcement types to send to the webhook
  announcementTypes?: enum[tombstone, broadcast, reply, reaction, profile, update][]
}

Responses

• 200

[DELETE]/v1/webhooks

• Summary
  Clear all previously registered webhooks

Responses

• 200

[GET]/v1/webhooks

• Summary
  Get the list of currently registered webhooks

Responses

• 200 Returns a list of registered webhooks

application/json

{
  // Webhook URL
  url: string
  // Announcement types to send to the webhook
  announcementTypes?: enum[tombstone, broadcast, reply, reaction, profile, update][]
}[]

[GET]/healthz

• Summary
  Check the health status of the service

Responses

• 200 Service is healthy

[GET]/livez

• Summary
  Check the live status of the service

Responses

• 200 Service is live

[GET]/readyz

• Summary
  Check the ready status of the service

Responses

• 200 Service is ready

References

#/components/schemas/ResetScannerDto

{
  // The block number to reset the scanner to
  blockNumber?: number
  // Number of blocks to rewind the scanner to (from `blockNumber` if supplied; else from latest block)
  rewindOffset?: number
  // Whether to schedule the new scan immediately or wait for the next scheduled interval
  immediate?: boolean
}

#/components/schemas/ChainWatchOptionsDto

{
  schemaIds?: number[]
  dsnpIds?: string[]
}

#/components/schemas/ContentSearchRequestDto

{
  // An optional client-supplied reference ID by which it can identify the result of this search
  clientReferenceId?: string
  // The block number to search (backward) from
  startBlock?: number
  // The number of blocks to scan (backwards)
  blockCount: number
  // The schemaIds/dsnpIds to filter by
  filters?: #/components/schemas/ChainWatchOptionsDto
  // A webhook URL to be notified of the results of this search
  webhookUrl: string
}

#/components/schemas/AnnouncementTypeName

{
  "type": "string",
  "description": "Announcement types to send to the webhook",
  "enum": [
    "tombstone",
    "broadcast",
    "reply",
    "reaction",
    "profile",
    "update"
  ]
}

#/components/schemas/WebhookRegistrationDto

{
  // Webhook URL
  url: string
  // Announcement types to send to the webhook
  announcementTypes?: enum[tombstone, broadcast, reply, reaction, profile, update][]
}

Configuration

ℹ️ Feel free to adjust your environment variables to taste. This application recognizes the following environment variables:

Best Practices

• Efficient Polling: Implement efficient polling mechanisms to minimize load on the service.
• Webhook Security: Secure webhooks by verifying the source of incoming requests.
• Rate Limiting: Apply rate limiting to prevent abuse and ensure fair usage of the service.