Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ivory.finance/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

A subscription links a channel to a set of filters. The alert_type controls which pipeline triggers it:
alert_typeWhat it watchesKey filters
filing_alertsNew SEC filings matching CIK, ticker, or form typefilter_ciks, filter_tickers, filter_form_types
keyword_alertsFiling text containing one or more keywords or phrasesfilter_keywords (required)
price_alertsMarket price thresholds(coming soon)
All filter fields are optional — omitting a field means “match all”. The exception is filter_keywords, which is required for keyword_alerts subscriptions. Combining filters — within a filing_alerts subscription, a filing must match all supplied filters. For example, a subscription with filter_tickers: ["AAPL"] and filter_form_types: ["8-K"] only triggers for Apple 8-K filings. Country and language scope the subscription to a geographic market and the language in which notifications are formatted. Both default to US / en.

​
Create a subscription

POST /v1/notifications/subscriptions
Headers
HeaderRequiredDescription
X-API-KeyYesYour API key
Content-TypeYesapplication/json
Body fields
FieldTypeDefaultDescription
channel_iduuid—Required. ID of the channel to trigger
namestringnullOptional label
alert_typestringfiling_alertsfiling_alerts · keyword_alerts · price_alerts
countrystringUSISO 3166-1 alpha-2 market scope (see supported countries)
languagestringenISO 639-1 notification language (see supported languages)
filter_ciksstring[]nullCIK numbers to watch (null = all)
filter_tickersstring[]nullTicker symbols to watch — resolved to CIKs at creation time
filter_form_typesstring[]nullForm types to watch, e.g. ["8-K", "10-K"] (null = all)
filter_keywordsstring[]nullRequired for keyword_alerts. Plain-text keywords or phrases to scan for
Keywords are normalized with NFKC + Unicode casefold before storage, so the match is case-insensitive and handles full-width characters, ligatures, and Unicode variants (e.g. ß → ss, Ａ → A). You can supply them in any case — "Merger", "MERGER", and "merger" all produce the same pattern.
curl -X POST https://api.ivory.finance/v1/notifications/subscriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "AAPL 8-K alerts",
    "alert_type": "filing_alerts",
    "filter_tickers": ["AAPL"],
    "filter_form_types": ["8-K"]
  }'
Response 
{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "channel_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "AAPL 8-K alerts",
  "alert_type": "filing_alerts",
  "country": "US",
  "language": "en",
  "filter_ciks": ["0000320193"],
  "filter_tickers": ["AAPL"],
  "filter_form_types": ["8-K"],
  "filter_keywords": null,
  "is_active": true,
  "created_at": "2026-02-24T10:05:00Z"
}
filter_tickers are resolved to filter_ciks at creation time using the companies table. Both are stored so you can see your original ticker input. Keyword subscriptions return filter_keywords with the raw strings you supplied; normalized forms are stored internally for matching.

​
List subscriptions

GET /v1/notifications/subscriptions
Returns all subscriptions for your account, joined with channel name and type. Query parameters
ParameterTypeDescription
alert_typestringOptional. Filter results to a single pipeline: filing_alerts · keyword_alerts · price_alerts
curl https://api.ivory.finance/v1/notifications/subscriptions \
  -H "X-API-Key: YOUR_API_KEY"
Response 
{
  "subscriptions": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "channel_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "channel_name": "My Slack",
      "channel_type": "slack",
      "alert_type": "filing_alerts",
      "country": "US",
      "language": "en",
      "name": "AAPL 8-K alerts",
      "filter_ciks": ["0000320193"],
      "filter_tickers": ["AAPL"],
      "filter_form_types": ["8-K"],
      "filter_keywords": null,
      "is_active": true,
      "created_at": "2026-02-24T10:05:00Z",
      "updated_at": null
    }
  ]
}

​
Get a subscription

GET /v1/notifications/subscriptions/{id}
Fetch a single subscription by ID. 
curl https://api.ivory.finance/v1/notifications/subscriptions/a1b2c3d4-0000-0000-0000-000000000001 \
  -H "X-API-Key: YOUR_API_KEY"
Response 
{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "channel_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "channel_name": "My Slack",
  "channel_type": "slack",
  "alert_type": "filing_alerts",
  "country": "US",
  "language": "en",
  "name": "AAPL 8-K alerts",
  "filter_ciks": ["0000320193"],
  "filter_tickers": ["AAPL"],
  "filter_form_types": ["8-K"],
  "filter_keywords": null,
  "is_active": true,
  "created_at": "2026-02-24T10:05:00Z",
  "updated_at": null
}
Returns 404 if the subscription ID does not exist or belongs to a different account.

​
Update a subscription

PUT /v1/notifications/subscriptions/{id}
All fields are optional — only supplied fields are updated.
FieldNotes
nameRename the subscription
is_activePause (false) or resume (true) delivery
alert_typeChange the pipeline that triggers this subscription
countryUpdate market scope
languageUpdate notification language
filter_ciksReplace CIK filter list
filter_tickersReplace ticker filter list
filter_form_typesReplace form-type filter list
filter_keywordsReplaces the full keyword set for keyword_alerts subscriptions; new keywords are registered automatically
curl -X PUT https://api.ivory.finance/v1/notifications/subscriptions/a1b2c3d4-0000-0000-0000-000000000001 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

​
Delete a subscription

DELETE /v1/notifications/subscriptions/{id}

curl -X DELETE https://api.ivory.finance/v1/notifications/subscriptions/a1b2c3d4-0000-0000-0000-000000000001 \
  -H "X-API-Key: YOUR_API_KEY"
Deleting a keyword_alerts subscription does not remove the keyword patterns from your account — those are shared across subscriptions. To stop keyword scanning entirely, delete all keyword_alerts subscriptions for your account.

​
Supported countries and languages

country (ISO 3166-1 alpha-2) US CA GB AU DE FR JP IN BR SG HK CN KR ES IT NL CH SE NO DK FI NZ IE ZA MX AE SA IL language (ISO 639-1) en fr es de ja zh pt ko ar hi it nl sv no da fi he tr