> ## Documentation Index > Fetch the complete documentation index at: https://docs.sigmora.org/llms.txt > Use this file to discover all available pages before exploring further. # Save Topic Monitor > Compile and save one channel-owned Topic Monitor. The saved phrases, exclusions, sources, cadence and notification choices belong to this Brand only. A shared corpus observation never becomes a discovery unless it matches this channel’s saved terms. Saving this monitor only configures source collection; it never starts content generation or publishing. ## OpenAPI ````yaml /openapi.json put /v1/topic-monitors/{brandId} openapi: 3.1.0 info: title: Sigmora API version: 1.0.0 description: >- The priced, versioned public API. Every call authenticates with a workspace API key (`Authorization: Bearer sk_live_…`), names the project it files its output under, and reports what it cost. `GET /v1/capabilities` answers what this deployment can serve right now and at what price; anything it reports as unavailable answers 503 `capability_unavailable` rather than 404. servers: - url: https://api.sigmora.org security: - bearerAuth: [] tags: - name: Meta description: What this deployment serves, what it costs, and what you have spent. - name: Projects description: The container every capability files its output under. - name: Sessions description: Durable bindings between an external harness session and one project. - name: Assets description: 'Project media: direct-to-storage uploads, imports, ingest and transcripts.' - name: Jobs description: Where every asynchronous capability is collected, whatever produced it. - name: Text description: Scripts, research, articles, translation and question sets. - name: Video description: Narrated renders, footage edits, shorts and moment selection. - name: UGC description: >- Creator-led vertical videos: AI creators, their faces and voices, frames and clips. - name: Editing description: >- Sigma, the editor: conversational turns, granular transcript edits, approvals. - name: 3D description: Animated 3D renders from a description or a photograph. - name: Image description: Thumbnails, sized for the platform they are posted to. - name: Audio description: Generated music and audio engineering in Audiotool projects. - name: Publishing description: Connected destinations and queued posts. - name: Webhooks description: Signed, at-least-once delivery of job and publishing events. - name: Workflows description: Context snapshots, versioned recipes, costed proposals and their runs. - name: Agents description: Describe an outcome and let a bounded plan of capabilities run. - name: Research description: >- Observed hooks, creator outliers and production briefs from saved analyses. - name: Themes description: The canonical content taxonomy, and the niche profiles built on it. - name: Signals description: Evidence-backed trends and scored viral content. - name: Discovery description: Compiled watch plans, their runs, and source freshness. - name: Watchlist description: 'Accounts you watch: their usual reach and the posts that beat it.' - name: Performance description: Your own channels' videos against their usual, and fixes to live videos. - name: Autopilot description: The durable trend-to-distribution workflow and its checkpoints. - name: Campaigns description: Distribution records shared by the API, the dashboard and autopilot. - name: Brands description: >- Cross-platform identities with their own voice, rules and publishing commitments. - name: Products description: What a campaign promotes. paths: /v1/topic-monitors/{brandId}: put: tags: - Discovery summary: Save Topic Monitor description: >- Compile and save one channel-owned Topic Monitor. The saved phrases, exclusions, sources, cadence and notification choices belong to this Brand only. A shared corpus observation never becomes a discovery unless it matches this channel’s saved terms. Saving this monitor only configures source collection; it never starts content generation or publishing. operationId: putTopicMonitorsByBrandId parameters: - name: brandId in: path required: true description: The Brand whose discovery plan this is. GET /v1/brands lists them. schema: type: string minLength: 1 maxLength: 200 description: The Brand whose discovery plan this is. GET /v1/brands lists them. examples: - brd_4b81 requestBody: required: true content: application/json: schema: type: object properties: intent: description: >- The channel-specific content opportunity the monitor should discover. type: string minLength: 10 maxLength: 500 keywords: description: Optional channel-specific search phrases. Send at most 12. maxItems: 12 type: array items: type: string minLength: 2 maxLength: 120 excludeKeywords: description: >- Optional phrases that exclude irrelevant search results. Send at most 20. maxItems: 20 type: array items: type: string minLength: 2 maxLength: 120 enabled: description: >- Whether scheduled discovery runs should occur. Defaults to false when first created, so saving a plan does not start automation unexpectedly. type: boolean platforms: description: >- Sources to watch. Accepted values are shown below; omit to keep the saved selection. minItems: 1 maxItems: 10 type: array items: type: string enum: - youtube_shorts - instagram_reels - facebook_reels - tiktok - twitter - reddit - news - medium - google_news - google_web regionCode: description: >- Two-letter ISO 3166-1 country code used for regional results. examples: - US type: string minLength: 2 maxLength: 2 discoveryIntervalMinutes: description: >- Minutes between full discovery runs. 15 to 43,200. Scheduled discovery runs at most every 360 minutes, so a shorter interval runs at that floor. Scheduled discoveries are bounded at 32 a day across all plans by default, spread evenly over the UTC day; POST /v1/discovery/runs runs one now. type: integer minimum: 15 maximum: 43200 refreshIntervalMinutes: description: >- Minutes between metric refreshes for previously found content. 15 to 43,200. Scheduled refreshes run at most every 30 minutes, so a shorter interval runs at that floor. Scheduled refreshes are bounded at 96 a day across all plans by default (plans on one primary theme share a refresh), spread evenly over the UTC day. type: integer minimum: 15 maximum: 43200 minimumSourceCount: description: >- Distinct selected sources required before a new finding may notify. Defaults to two when possible. type: integer minimum: 1 maximum: 10 notification: description: >- Channel-owned in-app/email notification preferences. Email is opt-in. type: object properties: inApp: description: >- Whether qualifying discoveries create an in-app and browser/mobile notice. type: boolean email: description: Whether qualifying discoveries also send an owner email. type: boolean minimumScore: description: >- Minimum 0–100 topic score required before a notification is sent. type: integer minimum: 0 maximum: 100 minimumEvidence: description: >- Minimum number of supporting evidence items required before notifying. type: integer minimum: 1 maximum: 20 searchDemand: description: >- Optional bounded YouTube public-search sampling. Scores are directional, not search-volume forecasts. type: object properties: enabled: description: >- Whether to include bounded public-search demand signals in the monitor. type: boolean maxQueries: description: >- Maximum public-search demand queries per run, from 1 through 4. type: integer minimum: 1 maximum: 4 example: intent: >- Budgeting habits that help first-job earners build an emergency fund. keywords: - first salary budget enabled: true platforms: - youtube_shorts - tiktok notification: inApp: true email: false minimumScore: 70 responses: '200': description: Success. content: application/json: schema: type: object properties: success: type: boolean const: true config: $ref: '#/components/schemas/DiscoveryPlan' description: Saved discovery settings and their compiled query plan. health: $ref: '#/components/schemas/DiscoveryHealth' description: Source readiness and collection freshness. required: - success - config - health additionalProperties: {} '400': description: 'Failure. `code` is one of: invalid_request.' content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: 'Failure. `code` is one of: unauthorized.' content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: 'Failure. `code` is one of: insufficient_credits, budget_capped.' content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: 'Failure. `code` is one of: forbidden, origin_not_allowed.' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: 'Failure. `code` is one of: not_found.' content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: 'Failure. `code` is one of: conflict.' content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: 'Failure. `code` is one of: payload_too_large.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: 'Failure. `code` is one of: rate_limited.' content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: 'Failure. `code` is one of: upstream_error, internal_error.' content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- Failure. `code` is one of: capability_unavailable, upstream_unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: DiscoveryPlan: type: object properties: id: type: string description: Discovery configuration id. contentBrandId: type: string description: Brand this configuration belongs to. enabled: type: boolean description: Whether scheduled runs are enabled. platforms: type: array items: type: string enum: - youtube_shorts - instagram_reels - facebook_reels - tiktok - twitter - reddit - news - medium - google_news - google_web description: Configured source platforms. regionCode: type: string description: Two-letter regional country code. discoveryIntervalMinutes: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Minutes between full discovery runs. refreshIntervalMinutes: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Minutes between metric refreshes. minimumSourceCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Distinct configured sources required before a new discovery may alert. notification: type: object properties: inApp: type: boolean description: >- Save the channel-owned discovery notice and dispatch browser/mobile notification. email: type: boolean description: Send a batched owner email when a new qualifying signal appears. minimumScore: type: integer minimum: 0 maximum: 100 minimumEvidence: type: integer minimum: 1 maximum: 20 required: - inApp - email - minimumScore - minimumEvidence description: Channel-scoped notification choices. searchDemand: type: object properties: enabled: type: boolean description: >- Use a bounded public YouTube search sample for directional demand. maxQueries: type: integer minimum: 1 maximum: 4 required: - enabled - maxQueries description: Provider-quota guard for directional search-demand enrichment. queryPlan: $ref: '#/components/schemas/DiscoveryQueryPlan' description: Stored watch plan used by discovery runs. lastDiscoveryAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ - type: 'null' description: Last full run time, or null before the first run. lastRefreshAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ - type: 'null' description: Last metric refresh time, or null before the first refresh. createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ required: - id - contentBrandId - enabled - platforms - regionCode - discoveryIntervalMinutes - refreshIntervalMinutes - minimumSourceCount - notification - searchDemand - queryPlan - lastDiscoveryAt - lastRefreshAt - createdAt - updatedAt additionalProperties: {} description: Saved discovery settings and their compiled query plan. DiscoveryHealth: type: object properties: status: type: string enum: - ready - degraded - blocked description: Overall readiness across configured sources. readySources: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Configured sources that can currently be invoked. configuredSources: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total configured sources. sources: type: array items: type: object properties: platform: type: string enum: - youtube_shorts - instagram_reels - facebook_reels - tiktok - twitter - reddit - news - medium - google_news - google_web status: type: string enum: - ready - missing_credentials reason: description: Why the source is unavailable, or null when ready. type: - string - 'null' queryMode: type: string enum: - provider-query - broad-ingest-theme-filter - rss-tag-feed - rss-search lastDiscoveryAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ - type: 'null' lastRefreshAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ - type: 'null' required: - platform - status - reason - queryMode - lastDiscoveryAt - lastRefreshAt additionalProperties: {} description: Readiness and freshness for each configured source. limitation: type: string description: What readiness does and does not guarantee. required: - status - readySources - configuredSources - sources - limitation additionalProperties: {} description: Source readiness and collection freshness. Error: type: object required: - success - error - code properties: success: const: false error: type: string description: >- Human-readable. Copy may change between releases — do not match on it. code: type: string enum: - invalid_request - unauthorized - forbidden - origin_not_allowed - not_found - conflict - payload_too_large - insufficient_credits - budget_capped - content_not_cleared - rate_limited - capability_unavailable - upstream_unavailable - upstream_error - internal_error description: Stable machine-readable cause. Branch on this. details: description: Optional structured context, e.g. the credits shortfall. requestId: type: string description: >- Identifies this request in our logs. Include it when you contact support. timestamp: type: string format: date-time description: When the failure was produced. DiscoveryQueryPlan: type: object properties: intent: type: string excludeKeywords: type: array items: type: string version: type: string description: Query-plan compiler version. primaryThemeId: type: string description: Brand theme the plan is centered on. themeIds: type: array items: type: string description: Canonical themes the plan watches. seedTerms: type: array items: type: string description: Terms compiled from the Brand profile. queries: type: array items: type: object properties: platform: type: string enum: - youtube_shorts - instagram_reels - facebook_reels - tiktok - twitter - reddit - news - medium - google_news - google_web description: Source this query runs against. terms: type: array items: type: string description: Search/watch terms sent to or applied for the source. intents: type: array items: type: string enum: - momentum - news - controversy - questions - competitors description: >- Signals this query is intended to find. `competitors` appears only on legacy plans; new topic-monitor plans never use it. required: - platform - terms - intents additionalProperties: {} description: Platform-specific watch queries. compiledAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ description: When this reproducible plan was compiled. basis: type: array items: type: string description: Brand fields and taxonomy context used to compile it. required: - version - primaryThemeId - themeIds - seedTerms - queries - compiledAt - basis additionalProperties: {} description: Stored watch plan used by discovery runs. securitySchemes: bearerAuth: type: http scheme: bearer description: A workspace API key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.