financialfilings-com Watchlist API
The companies you follow. Filters and webhooks can use it.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/financialfilings-com:financialfilings-com-watchlist-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: FinancialFilings Watchlist API
version: 1.4.0
description: 'Filings and company data for listed companies across the G20 and Europe. Send your API key in the `X-API-Key` header on every request. New here? Start with the quickstart.
**Credits.** Every call costs credits, and each endpoint below shows its price. `X-Credits-Charged` on the response says what a call cost, and `GET /usage/` shows the month so far. A free account gets a monthly allowance. Webhooks are an Enterprise feature. Pricing: https://financialfilings.com/developers/
**Rate limits.** Responses carry `X-RateLimit-Burst-Limit` (a rate such as `50/second`), `X-RateLimit-Monthly-Limit`, `X-RateLimit-Monthly-Remaining` and `X-RateLimit-Monthly-Unit` (`requests` or `credits`). All four are strings and can be non-numeric (for example `Unlimited`); the last two are left out when they don''t apply.'
termsOfService: https://financialfilings.com/api-terms/
contact:
name: API Support
url: https://financialfilings.com/
email: api@financialfilings.com
servers:
- url: https://api.financialreports.eu
description: Production API Gateway
tags:
- name: Watchlist
description: The companies you follow. Filters and webhooks can use it.
paths:
/watchlist/:
get:
operationId: watchlist_retrieve
description: '**Cost:** 1 credit per request.
---
The companies on your watchlist, paginated.'
summary: Get Watchlist
tags:
- Watchlist
security:
- ApiKeyAuth: []
- CognitoJWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistPage'
examples:
Success:
value:
- id: 14
name: adidas AG
- id: 6910
name: Mega Or Holdings Ltd.
description: Successfully retrieved the watchlist.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
examples:
Error:
value:
detail: Authentication credentials were not provided or are invalid.
description: Authentication credentials were not provided or are invalid.
'403':
description: Missing or invalid API key, or the plan does not include this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
examples:
MissingCredentials:
summary: No X-API-Key header
value:
detail: Authentication credentials were not provided.
type: authentication_required
resolution: 'Send your API key in the X-API-Key request header, e.g. curl -H "X-API-Key: <your key>" https://api.financialreports.eu/filings/ . A browser address bar never sends this header. No key yet? Get a free one at https://financialfilings.com/accounts/api-dashboard/ .'
dashboard_url: https://financialfilings.com/accounts/api-dashboard/
InvalidKey:
summary: Unknown or inactive API key
value:
detail: Invalid or inactive API key.
PlanDoesNotPermit:
summary: Plan does not include this endpoint
value:
detail: Your current plan does not permit access. Requires a plan that includes **structured financials**.
'429':
description: Rate limit, plan quota or spend cap reached.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
examples:
BurstLimit:
summary: Too many requests per minute
value:
error: Too Many Requests
detail: Request was throttled. Expected available in 12 seconds.
retry_after_seconds: 12
scope: burst
type: burst_limit_exceeded
message: 'Rate limit reached: 120 requests per minute.'
resolution: 'Retry after 12 seconds (Retry-After header). Pay-as-you-go raises this to 50/sec: https://financialfilings.com/accounts/payg/'
rate_limit: 120/minute
payg_url: https://financialfilings.com/accounts/payg/
/watchlist/companies/:
post:
operationId: watchlist_companies_create
description: '**Cost:** 1 credit per request.
---
Adds a company to your watchlist.'
summary: Add Company to Watchlist
tags:
- Watchlist
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistAction'
examples:
ExampleRequest:
value:
company_id: 14
summary: Example Request
description: An example of a request body to add a company to the watchlist.
required: true
security:
- ApiKeyAuth: []
- CognitoJWT: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistResponse'
examples:
Success:
value:
status: success
message: Company added to watchlist.
company_id: 14
description: Company successfully added to the watchlist.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistResponse'
examples:
CompanyAlreadyInWatchlist:
value:
status: error
message: Company already in watchlist.
company_id: 14
summary: Company already in watchlist
ValidationError:
value:
company_id:
- This field may not be blank.
- A valid integer is required.
summary: Validation Error
description: Bad Request. The company may already be in the watchlist or the input was invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
examples:
Error:
value:
detail: Authentication credentials were not provided or are invalid.
description: Authentication credentials were not provided or are invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
description: Forbidden. The watchlist is locked by an administrator.
'429':
description: Rate limit, plan quota or spend cap reached.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
examples:
BurstLimit:
summary: Too many requests per minute
value:
error: Too Many Requests
detail: Request was throttled. Expected available in 12 seconds.
retry_after_seconds: 12
scope: burst
type: burst_limit_exceeded
message: 'Rate limit reached: 120 requests per minute.'
resolution: 'Retry after 12 seconds (Retry-After header). Pay-as-you-go raises this to 50/sec: https://financialfilings.com/accounts/payg/'
rate_limit: 120/minute
payg_url: https://financialfilings.com/accounts/payg/
/watchlist/companies/{company_id}/:
delete:
operationId: watchlist_companies_destroy
description: '**Cost:** 1 credit per request.
---
Removes the company in the path from your watchlist.'
summary: Remove Company from Watchlist
parameters:
- in: path
name: company_id
schema:
type: integer
required: true
tags:
- Watchlist
security:
- ApiKeyAuth: []
- CognitoJWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistResponse'
examples:
Success:
value:
status: success
message: Company removed from watchlist.
company_id: 14
description: Company successfully removed from the watchlist.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
examples:
Error:
value:
detail: Authentication credentials were not provided or are invalid.
description: Authentication credentials were not provided or are invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
description: Forbidden. The watchlist is locked by an administrator.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistResponse'
examples:
CompanyNotInWatchlist:
value:
status: error
message: Company not in watchlist.
company_id: 14
summary: Company not in watchlist
description: Not Found. The company either does not exist or was not in the user's watchlist.
'429':
description: Rate limit, plan quota or spend cap reached.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
examples:
BurstLimit:
summary: Too many requests per minute
value:
error: Too Many Requests
detail: Request was throttled. Expected available in 12 seconds.
retry_after_seconds: 12
scope: burst
type: burst_limit_exceeded
message: 'Rate limit reached: 120 requests per minute.'
resolution: 'Retry after 12 seconds (Retry-After header). Pay-as-you-go raises this to 50/sec: https://financialfilings.com/accounts/payg/'
rate_limit: 120/minute
payg_url: https://financialfilings.com/accounts/payg/
/watchlist/companies/bulk-add/:
post:
operationId: watchlist_companies_bulk_add_create
description: '**Cost:** 1 credit per request.
---
Adds up to 100 companies to your watchlist. Companies already on it are skipped.'
summary: Bulk Add Companies to Watchlist
tags:
- Watchlist
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkWatchlist'
examples:
ExampleRequest:
value:
company_ids:
- 14
- 27
- 42
summary: Example Request
required: true
security:
- ApiKeyAuth: []
- CognitoJWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BulkWatchlistResponse'
examples:
Success:
value:
status: success
message: 3 companies added to watchlist.
company_ids:
- 14
- 27
- 42
description: Companies successfully added.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
description: Validation error.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
examples:
Error:
value:
detail: Authentication credentials were not provided or are invalid.
description: Authentication credentials were not provided or are invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
description: Forbidden. The watchlist is locked by an administrator.
'429':
description: Rate limit, plan quota or spend cap reached.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
examples:
BurstLimit:
summary: Too many requests per minute
value:
error: Too Many Requests
detail: Request was throttled. Expected available in 12 seconds.
retry_after_seconds: 12
scope: burst
type: burst_limit_exceeded
message: 'Rate limit reached: 120 requests per minute.'
resolution: 'Retry after 12 seconds (Retry-After header). Pay-as-you-go raises this to 50/sec: https://financialfilings.com/accounts/payg/'
rate_limit: 120/minute
payg_url: https://financialfilings.com/accounts/payg/
/watchlist/companies/bulk-remove/:
post:
operationId: watchlist_companies_bulk_remove_create
description: '**Cost:** 1 credit per request.
---
Removes up to 100 companies from your watchlist. Companies not on it are skipped.'
summary: Bulk Remove Companies from Watchlist
tags:
- Watchlist
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkWatchlist'
examples:
ExampleRequest:
value:
company_ids:
- 14
- 27
summary: Example Request
required: true
security:
- ApiKeyAuth: []
- CognitoJWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BulkWatchlistResponse'
examples:
Success:
value:
status: success
message: 2 companies removed from watchlist.
company_ids:
- 14
- 27
description: Companies successfully removed.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
description: Validation error.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
examples:
Error:
value:
detail: Authentication credentials were not provided or are invalid.
description: Authentication credentials were not provided or are invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
description: Forbidden. The watchlist is locked by an administrator.
'429':
description: Rate limit, plan quota or spend cap reached.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
examples:
BurstLimit:
summary: Too many requests per minute
value:
error: Too Many Requests
detail: Request was throttled. Expected available in 12 seconds.
retry_after_seconds: 12
scope: burst
type: burst_limit_exceeded
message: 'Rate limit reached: 120 requests per minute.'
resolution: 'Retry after 12 seconds (Retry-After header). Pay-as-you-go raises this to 50/sec: https://financialfilings.com/accounts/payg/'
rate_limit: 120/minute
payg_url: https://financialfilings.com/accounts/payg/
components:
schemas:
BulkWatchlistResponse:
type: object
properties:
status:
type: string
description: Indicates the status of the operation (e.g., 'success', 'error').
message:
type: string
description: A human-readable message describing the outcome.
company_ids:
type: array
items:
type: integer
description: The IDs of the companies affected by the action.
required:
- message
- status
WatchlistCompany:
type: object
properties:
id:
type: integer
readOnly: true
description: The unique identifier of the company.
name:
type: string
readOnly: true
description: The name of the company.
required:
- id
- name
WatchlistAction:
type: object
properties:
company_id:
type: integer
description: ID of the company.
required:
- company_id
BulkWatchlist:
type: object
properties:
company_ids:
type: array
items:
type: integer
description: Company IDs, 1 to 100.
maxItems: 100
minItems: 1
required:
- company_ids
RateLimitError:
type: object
description: Body of a 429 response. The `Retry-After` header carries the same wait as `retry_after_seconds`. Only `detail` is always present.
properties:
detail:
type: string
description: A human-readable message describing the error.
error:
type: string
description: Always `Too Many Requests`.
retry_after_seconds:
type:
- integer
- 'null'
description: Seconds until the request may be retried, when known.
scope:
type:
- string
- 'null'
description: Which limit was hit, e.g. `burst`, `quota` or `payg_velocity`.
type:
type: string
description: Machine-readable error code, e.g. `burst_limit_exceeded`, `quota_limit_exceeded`, `daily_spend_cap_reached` or `monthly_spend_ceiling_reached`.
message:
type: string
description: A human-readable explanation of the limit.
resolution:
type: string
description: A human-readable hint on what to do next.
upgrade_url:
type: string
description: 'Where to upgrade: the pay-as-you-go card page for free accounts, else the plans page (quota errors).'
limit:
type: integer
description: The plan allowance that was used up (quota errors).
interval:
type: string
description: '`monthly` or `annual` (quota errors).'
resets_on:
type: string
format: date
description: UTC date the allowance resets (quota errors).
rate_limit:
type: string
description: The per-minute limit that refused the request, e.g. `120/minute` (burst errors).
payg_url:
type: string
description: Where to enable pay-as-you-go (quota and burst errors, when it applies).
dashboard_url:
type: string
description: Where to see current spend (spend-cap and spend-ceiling errors).
contact_url:
type: string
description: Where to ask for a higher limit (spend-cap and spend-ceiling errors).
required:
- detail
WatchlistResponse:
type: object
properties:
status:
type: string
description: Indicates the status of the operation (e.g., 'success', 'error').
message:
type: string
description: A human-readable message describing the outcome.
company_id:
type: integer
description: The ID of the company related to the action, if applicable.
required:
- message
- status
ErrorDetail:
type: object
properties:
detail:
type: string
description: A human-readable message describing the error.
type:
type: string
description: Machine-readable error code, e.g. `authentication_required`. Present on some errors only.
resolution:
type: string
description: A human-readable hint on how to fix the request. Present on some errors only.
error_type:
type: string
description: Machine-readable error code on validation errors. Present on some errors only.
required:
- detail
WatchlistPage:
type: object
description: 'One page of your watchlist: the standard pagination fields plus `is_locked`.'
properties:
count:
type: integer
description: Total number of companies on the watchlist.
next:
type:
- string
- 'null'
format: uri
description: URL of the next page of results, or null on the last page.
previous:
type:
- string
- 'null'
format: uri
description: URL of the previous page of results, or null on the first page.
results:
type: array
items:
$ref: '#/components/schemas/WatchlistCompany'
description: Companies on the current page.
is_locked:
type: boolean
description: Whether the watchlist is locked by an administrator.
required:
- count
- is_locked
- next
- previous
- results
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: 'Server-to-server API key authentication. Provide your key in the `X-API-Key` request header. Keys can be generated and rotated from your account dashboard: https://financialfilings.com/profile/'
CognitoJWT:
type: http
scheme: bearer
bearerFormat: JWT
description: 'AWS Cognito-issued JWT access token. Provide the token in the `Authorization` header as: `Authorization: Bearer <access_token>`. Tokens are issued via the Cognito hosted UI or the OAuth2 authorization code flow at `https://auth.financialreports.eu`.'