Update Keyword Watchlist

curl -X PUT \
  "https://api.outx.ai/api-keyword-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Watchlist Name",
    "fetchFreqInHours": 24
  }'

curl -X PUT \
  "https://api.outx.ai/api-keyword-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "keywords": [
      {
        "keyword": "CTO",
        "required_keywords": ["hiring"],
        "excluded_keywords": ["recruiter", "spam"]
      },
      "founder"
    ],
    "labels": [
      { "name": "hiring", "description": "Job postings", "default": true },
      { "name": "founder-post", "description": "Posts from founders", "default": false }
    ]
  }'

curl -X PUT \
  "https://api.outx.ai/api-keyword-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "disable": true
  }'

const response = await fetch("https://api.outx.ai/api-keyword-watchlist", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    id: "550e8400-e29b-41d4-a716-446655440000",
    keywords: [
      {
        keyword: "CTO",
        required_keywords: ["hiring"],
        excluded_keywords: ["recruiter", "spam"],
      },
    ],
    labels: [{ name: "hiring", description: "Job postings" }],
  }),
});

import requests

url = 'https://api.outx.ai/api-keyword-watchlist'
headers = {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY',
}

# Update keywords and labels
payload = {
    'id': '550e8400-e29b-41d4-a716-446655440000',
    'keywords': [
        {
            'keyword': 'CTO',
            'required_keywords': ['hiring'],
            'excluded_keywords': ['recruiter', 'spam'],
        }
    ],
    'labels': [
        {'name': 'hiring', 'description': 'Job postings'},
    ],
}

response = requests.put(url, headers=headers, json=payload)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Updated Watchlist Name",
  "fetchFreqInHours": 24,
  "disable": false,
  "updated": true,
  "message": "Watchlist updated successfully"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "updated": true,
  "message": "Watchlist updated successfully",
  "keywords": ["cto", "founder"],
  "results": [
    {
      "success": true,
      "keyword": "cto",
      "keyword_id": "660e8400-e29b-41d4-a716-446655440001"
    },
    {
      "success": true,
      "keyword": "founder",
      "keyword_id": "660e8400-e29b-41d4-a716-446655440002"
    }
  ],
  "labels": [
    { "key": "hiring", "description": "Job postings", "default": true },
    { "key": "founder-post", "description": "Posts from founders", "default": false }
  ]
}

Modify an existing keyword watchlist without losing its ID or collected posts. Every field is optional, send only the properties you want to change.

Platform: LinkedIn. This endpoint updates LinkedIn keyword watchlists only. Reddit watchlists are updated with PUT /api-reddit-watchlist (same body shape). See Choose a watchlist type.

Disabled watchlists reject updates. If the watchlist is paused (disabled: true on GET), any PUT except an explicit re-enable returns 409 This watchlist is disabled. Enable it before updating it. Re-enable first with { "id": "...", "disable": false }, then apply your changes.The exception is patch mode only. A prompt-mode PUT is refused even when it is sent alongside disable: false, because prompt mode does not read disable. Re-enable in its own call, then send the new prompt.

The endpoint accepts two body shapes. Either patch fields (documented below) or send a new prompt to have OutX regenerate the entire keyword set in the background (Prompt mode at the bottom of this page).

Request Body (patch mode)

string

required

Watchlist ID to update.

string

New watchlist name.

number

New fetch frequency. Allowed values: 1, 3, 6, 12, 24, 48, 72.

array

Patch the tracked keywords on the watchlist. Accepts the same shape as the Create endpoint, simple strings or advanced keyword objects with required_keywords, excluded_keywords (NOT), and include_all_required (AND vs OR over the required keywords).Simple format:

["hiring", "remote work"]

Advanced format:

[
  {
    "keyword": "CTO",
    "required_keywords": ["hiring", "founder", "vp"],
    "excluded_keywords": ["recruiter", "spam"],
    "include_all_required": false
  }
]

By default this replaces the set: the watchlist’s existing keywords are deleted and recreated from the new list, along with the collection task for each keyword (set append: true to add instead). Newly created keywords backfill recent matching posts automatically in the background. Updating keywords does not change existing labels. Omit the field to leave keywords untouched.

boolean

default:"false"

When true, the supplied keywords are added to the existing set instead of replacing it. Existing keyword tracking rows and tasks are kept, and only keywords whose primary keyword is not already on the list (case-insensitive) are created. Labels are left untouched unless labels is also provided.

array

Replace the custom labels on the watchlist. Same shape as Create: each label is a name (or key, so a GET response can be echoed back), a description, and an optional default flag marking it as a pre-applied feed filter (at most 2 true; if you set the flag on some labels but mark none true, the first is promoted). This is also how you change which labels are default: send the full array with the default booleans you want. See Intent labels & defaults.

[
  { "name": "hiring", "description": "Job postings", "default": true },
  { "name": "competitor", "description": "Competitor mentions", "default": false }
]

Labels are only changed when this field is sent, and sending it replaces the entire set (start from the current GET output; omitted labels are dropped). Updating keywords alone leaves your existing labels untouched, so a keyword edit will never wipe a hand-built label set. Omit labels to leave them as they are.

boolean

Set to true to pause tracking, false to resume. Pausing stops every collection task on the watchlist and flips disabled to true on the type’s GET endpoint, with disabledAt carrying the timestamp on the list response.

string | null

Update or clear the Slack webhook URL for this watchlist. Pass null to clear.

Semantics

Keyword replacement is wipe-and-recreate (default). Existing keyword_tracking rows and the collection task for each keyword are deleted, then new ones are created from the payload. Posts already collected are not deleted, they remain attached to the watchlist and visible via the Posts API.
Append mode keeps what you have. With append: true, existing keywords and tasks are kept and only the new, not-yet-present primary keywords are added.
New keywords backfill automatically. Whether replacing or appending, each newly created keyword backfills recent matching posts in the background, so it does not have to wait for the next live fetch to show results.
Labels are preserved unless you send labels. Updating keywords alone never overwrites existing labels. To change labels, pass a labels array.
Only the collection task for each keyword is touched. Any other work running on the same watchlist is left alone.
Partial updates are safe. Sending only { "id": "...", "name": "new name" } changes just the name; keywords, labels, and tasks are untouched.

curl -X PUT \
  "https://api.outx.ai/api-keyword-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Watchlist Name",
    "fetchFreqInHours": 24
  }'

curl -X PUT \
  "https://api.outx.ai/api-keyword-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "keywords": [
      {
        "keyword": "CTO",
        "required_keywords": ["hiring"],
        "excluded_keywords": ["recruiter", "spam"]
      },
      "founder"
    ],
    "labels": [
      { "name": "hiring", "description": "Job postings", "default": true },
      { "name": "founder-post", "description": "Posts from founders", "default": false }
    ]
  }'

curl -X PUT \
  "https://api.outx.ai/api-keyword-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "disable": true
  }'

const response = await fetch("https://api.outx.ai/api-keyword-watchlist", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    id: "550e8400-e29b-41d4-a716-446655440000",
    keywords: [
      {
        keyword: "CTO",
        required_keywords: ["hiring"],
        excluded_keywords: ["recruiter", "spam"],
      },
    ],
    labels: [{ name: "hiring", description: "Job postings" }],
  }),
});

import requests

url = 'https://api.outx.ai/api-keyword-watchlist'
headers = {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY',
}

# Update keywords and labels
payload = {
    'id': '550e8400-e29b-41d4-a716-446655440000',
    'keywords': [
        {
            'keyword': 'CTO',
            'required_keywords': ['hiring'],
            'excluded_keywords': ['recruiter', 'spam'],
        }
    ],
    'labels': [
        {'name': 'hiring', 'description': 'Job postings'},
    ],
}

response = requests.put(url, headers=headers, json=payload)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Updated Watchlist Name",
  "fetchFreqInHours": 24,
  "disable": false,
  "updated": true,
  "message": "Watchlist updated successfully"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "updated": true,
  "message": "Watchlist updated successfully",
  "keywords": ["cto", "founder"],
  "results": [
    {
      "success": true,
      "keyword": "cto",
      "keyword_id": "660e8400-e29b-41d4-a716-446655440001"
    },
    {
      "success": true,
      "keyword": "founder",
      "keyword_id": "660e8400-e29b-41d4-a716-446655440002"
    }
  ],
  "labels": [
    { "key": "hiring", "description": "Job postings", "default": true },
    { "key": "founder-post", "description": "Posts from founders", "default": false }
  ]
}

Response Fields

string

Watchlist ID that was updated.

string

Updated watchlist name (only present when name was in the request).

number

Updated fetch frequency (only present when fetchFreqInHours was in the request).

boolean

Current active/disabled status (only present when disable was in the request).

array

Array of primary keywords after the update (only present when keywords was in the request).

array

Per-keyword creation result (only present when keywords was in the request). Each entry has success, keyword, and either keyword_id or error.

array

Labels persisted on the watchlist (only present when labels or keywords was in the request).

boolean

Whether the update was successful.

string

Success message.

Error Responses

Status Code	Error Message	Description
400	Missing required parameter: id	Watchlist ID is required
400	No valid update fields provided	Body didn’t include any updatable fields
400	keywords array is required and must not be empty	`keywords` was passed but empty or not an array
400	No valid keywords provided after cleaning	All keywords were empty strings after normalization
400	Invalid fetchFreqInHours. Allowed values: 1, 3, 6, 12, 24, 48, 72 (hours)	Unsupported fetch frequency
400	disable must be a boolean value	`disable` sent as a non-boolean
400	Name cannot be empty	`name` was an empty or whitespace-only string
401	Missing API Key / Invalid API Key	Missing or invalid `x-api-key` header
404	Watchlist not found or access denied	Watchlist doesn’t exist, isn’t a keyword list, or isn’t yours
409	This watchlist is disabled. Enable it before updating it.	The watchlist is paused. Send `{ "id": "...", "disable": false }` first, then retry the update. Applies to both patch mode and prompt mode.
422	`prompt_not_specific_enough`	Prompt mode only. The replacement prompt cannot produce a usable feed. Nothing on the watchlist was changed.

See Error Codes for the full list, including 403 (plugin not active) and 405 (wrong HTTP method).

Prompt mode

Replace the prompt on an existing watchlist. OutX wipes the existing keywords and labels and regenerates them from the new prompt in the background. Use this when you want to redirect a watchlist to a different angle without recreating it.

If you send prompt together with patch fields (name, keywords, labels, disable, fetchFreqInHours, slack_webhook_url), the patch fields are silently ignored, prompt takes precedence. Unlike create (POST), update does not return an error when both are sent.

Request Body

string

required

Watchlist ID to update.

string

required

New natural-language prompt. OutX will regenerate keywords and labels from this, replacing the current set.

curl -X PUT \
  "https://api.outx.ai/api-keyword-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "prompt": "Track AI CRM tools, Salesforce alternatives, and enterprise sales automation"
  }'

const response = await fetch("https://api.outx.ai/api-keyword-watchlist", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    id: "550e8400-e29b-41d4-a716-446655440000",
    prompt:
      "Track AI CRM tools, Salesforce alternatives, and enterprise sales automation",
  }),
});

const result = await response.json();
console.log(result.message);

import requests

headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
}

payload = {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "prompt": "Track AI CRM tools, Salesforce alternatives, and enterprise sales automation",
}

response = requests.put(
    "https://api.outx.ai/api-keyword-watchlist",
    headers=headers,
    json=payload,
)

result = response.json()
print(result["message"])

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "prompt": "Track AI CRM tools, Salesforce alternatives, and enterprise sales automation",
  "updated": true,
  "message": "Prompt updated. Keywords and labels are being regenerated in the background."
}

What is kept and what is replaced

The prompt path is not a patch. It throws away the current keyword set and label set and builds new ones from the new prompt.

Kept	Replaced
`id` and `slug`	Every tracked keyword, and the collection job behind it
`name`	The whole label set
Posts already collected	The relevance objective and its scoring vector
`fetchFreqInHours`, Slack webhook, paused state	The stored prompt

You cannot change one keyword through the prompt path. Use the keywords field for that (replace by default, or add with append: true). The response confirms only that regeneration started. It carries no keywords and no labels, because they have not been generated yet. There is no completion flag to poll. The old keywords stay in place while the new set is generated, so “keywords is not empty” is true the whole time and tells you nothing. The reliable check:

Before the PUT, call GET /api-keyword-watchlist?id=… and keep the keyword_tracking[].id values.
After the PUT, poll the same call until every id in the response is one you did not see in step 1.
Keep polling until the number of keyword_tracking entries is the same in two consecutive responses. The rows are created one at a time, so a settled count is what says the swap finished.

A prompt-mode update backfills, like a keywords patch does. Once the new keywords are generated, each one pulls in recent matching posts, so the feed refills without waiting for the next fetch cycle. The Reddit twin does not: Reddit watchlists never backfill, on create or on update.

The app re-classifies old posts here; the API does not. When you change the prompt in the OutX app, it also re-runs classification over recent posts so they carry tags from the new label set. A prompt-mode PUT regenerates keywords and labels only, and classification stays forward-only: posts already enriched keep the tags they have. There is no API field to ask for re-enrichment.

The replacement prompt is checked before anything is touched, the same check that runs on create. A prompt that cannot produce a usable feed is refused with 422 prompt_not_specific_enough and the watchlist is left exactly as it was, so a bad prompt can never wipe a working watchlist. When the refusal body carries a question, relay it to your user word for word and retry with their answer. Full contract: When a prompt is refused.

Frequently Asked Questions

What properties can I update on a keyword watchlist?

You can update name, fetchFreqInHours, keywords, labels, disable, and slack_webhook_url, any combination. Every field except id is optional; unspecified fields are left unchanged.

What happens to my existing keywords when I update them?

When you pass a keywords array, the API deletes the watchlist’s existing keyword_tracking rows and the collection task for each keyword, then creates new ones from your payload. The watchlist ID stays the same, and previously collected posts remain accessible via the Posts API.

Does updating a watchlist reset existing collected data?

No. Changing the name, fetch frequency, keywords, or labels does not delete posts that have already been collected. If you update fetchFreqInHours, the new interval takes effect from the next scheduled fetch cycle.

Can I update labels without changing keywords?

Yes. Send only id and labels. The existing keywords and their tasks are untouched.

How do I change which labels are shown by default?

Fetch the current labels with GET ?id=…, flip the default booleans you want (at most 2 can be true), and PUT the full array back as labels. Keep the key and description strings unchanged so historical post tags keep matching. See Intent labels & defaults.

Do new or changed labels apply to posts I already collected?

No. Each post is classified into a label once, when it is first enriched. Updating or adding labels changes how future posts are classified but does not re-label posts that were already collected, they keep the tags they had. To re-classify recent posts against the new labels, those posts must be explicitly re-enriched (OutX re-runs classification over roughly the last 30 days). See How intent labels are calculated.

What if I only want to add or remove a single keyword?

To add keywords without disturbing the rest, send just the new keywords with append: true, only the ones not already on the list (case-insensitive) are created. To remove a keyword, fetch the current set with GET /api-keyword-watchlist?id=…, then send the full desired list back without append (default replace).

Getting Started

Authentication (OTP)

Keyword Watchlist

People Watchlist

Company Watchlist

Reddit Watchlist

Posts & Engagement

Team & Usage

LinkedIn Data

Integrations

Update Keyword Watchlist

Request Body (patch mode)

Semantics

Response Fields

Error Responses

Prompt mode

Request Body

What is kept and what is replaced

Frequently Asked Questions

​Request Body (patch mode)

​Semantics

​Response Fields

​Error Responses

​Prompt mode

​Request Body

​What is kept and what is replaced

​Frequently Asked Questions

Request Body (patch mode)

Semantics

Response Fields

Error Responses

Prompt mode

Request Body

What is kept and what is replaced

Frequently Asked Questions