Compabase Watchlist API
The Watchlist API from Compabase — 2 operation(s) for watchlist.
The Watchlist API from Compabase — 2 operation(s) for watchlist.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/compabase:compabase-watchlist-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a 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: 3.2.0
info:
title: Compabase Watchlist API
version: 1.0.0
description: 'Operations tagged Watchlist across 2 of this provider''s published API definitions: compabase-openapi.yaml, compabase-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://compabase.com/api/v1
description: Full URL
tags:
- name: Watchlist
paths:
/watchlist:
get:
tags:
- Watchlist
summary: List watchlist
description: 'Lists companies on the watchlist of the **user account linked to the API key**.
Requires `user_id` on the key.'
security:
- ApiKeyAuth: []
- BearerAuth: []
parameters:
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
responses:
'200':
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
description: Watchlist page.
content:
application/json:
schema:
type: object
example:
data: []
pagination:
total: 0
hasMore: false
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: API key is not linked to a user account.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
$ref: '#/components/responses/TooManyRequests'
operationId: getWatchlist
x-operation-id-source: derived
servers:
- url: https://compabase.com/api/v1
description: Full URL
/watchlist/krs/{krs}:
post:
tags:
- Watchlist
summary: Add company to watchlist
description: 'Adds a company to the **watchlist of the user account linked to the API key**.
The company is identified by **KRS** (Polish court registry number). Digits only;
leading zeros are optional (normalized to 10 digits server-side).
**Create-or-keep in one call, keyed by KRS:** if the company is already on the watchlist,
the response returns `already_following: true` and no duplicate entry is created, so the call
is safe to retry. `already_following` tells which branch ran.
**Reversible:** `DELETE /watchlist/krs/{krs}` removes the entry at any time.
Use `dry_run=true` to check the plan limit and the outcome without writing.
Requires an API key associated with a Compabase portal user account (`user_id` on the key).'
security:
- ApiKeyAuth: []
- BearerAuth: []
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/DryRun'
- name: krs
in: path
required: true
schema:
type: string
description: KRS input is normalized by stripping non-digits and left-padding to 10 digits. After normalization, KRS must contain exactly 10 digits; otherwise request fails with `400 INVALID_KRS`.
example: 0000028860
responses:
'200':
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
description: Company added to watchlist (or already followed).
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistAddResponse'
examples:
added:
summary: Newly added
value:
krs: 0000028860
entity_id: ad2ae683-ccbd-49c6-a85c-648024435cb5
already_following: false
created_at: '2026-05-20T14:30:00Z'
alreadyFollowing:
summary: Already on watchlist
value:
krs: 0000028860
entity_id: ad2ae683-ccbd-49c6-a85c-648024435cb5
already_following: true
created_at: '2026-05-15T09:00:00Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: API key is not linked to a user account.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: INVALID_API_KEY
message: This API key is not linked to a user account.
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
operationId: postWatchlistKrsByKrs
x-operation-id-source: derived
delete:
tags:
- Watchlist
summary: Remove company from watchlist
description: 'Removes a KRS company from the watchlist of the user linked to the API key.
Reverses `POST /watchlist/krs/{krs}`; the company can be added again at any time.
Idempotent: `removed: false` when the company was not on the list.
Use `dry_run=true` to see the outcome (`would_remove`) without writing.'
security:
- ApiKeyAuth: []
- BearerAuth: []
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/DryRun'
- name: krs
in: path
required: true
schema:
type: string
example: 0000028860
responses:
'200':
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
description: Removal result.
content:
application/json:
schema:
type: object
example:
krs: 0000028860
entity_id: ad2ae683-ccbd-49c6-a85c-648024435cb5
removed: true
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: API key is not linked to a user account.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
operationId: deleteWatchlistKrsByKrs
x-operation-id-source: derived
servers:
- url: https://compabase.com/api/v1
description: Full URL
webhooks:
watchlistEvent:
post:
tags:
- Watchlist
summary: Watchlist change event
description: 'Sent to the webhook URL configured in the portal (Settings → Notifications) or with the MCP tool
`set_webhook_url`, for every company on your watchlist that changes. Choose which event types
you receive in the same settings (default: all).
**Signature:** header `X-Compabase-Signature: t=,v1=`, where `v1` is
HMAC-SHA256 of the raw request body with your webhook secret.
Respond with any 2xx within 10 seconds; failed deliveries are retried.'
parameters:
- name: X-Compabase-Event
in: header
required: true
description: Event type, same as `event` in the body.
schema:
type: string
example: watchlist.board_changed
- name: X-Compabase-Signature
in: header
required: true
description: '`t=<unix timestamp>,v1=<HMAC-SHA256 hex of the raw body>`'
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistWebhookEvent'
example:
event: watchlist.board_changed
company:
entity_id: ad2ae683-ccbd-49c6-a85c-648024435cb5
name: Orlen S.A.
krs: 0000028860
nip: '7740001454'
city: Płock
is_active: true
revenue_total: 372000000000
profit_net: 5600000000
detected_at: '2026-11-11T07:30:00Z'
responses:
'200':
description: Delivery accepted. Any 2xx response is treated as success.
servers:
- url: https://compabase.com/api/v1
description: Full URL
components:
responses:
Unauthorized:
description: Missing, invalid, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 401
statusMessage: Unauthorized
message: Unauthorized
data:
message: Missing or invalid API key.
BadRequest:
description: Invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidKrs:
summary: Invalid KRS value
value:
statusCode: 400
statusMessage: Invalid krs
message: Invalid krs
data:
error:
code: INVALID_KRS
message: After normalization, KRS must contain exactly 10 digits.
details:
parameter: krs
invalidCursor:
summary: Invalid cursor format
value:
statusCode: 400
statusMessage: Invalid cursor
message: Invalid cursor
data:
error:
code: INVALID_CURSOR
message: Cursor must be a valid UUID.
details:
parameter: cursor
invalidRange:
summary: Invalid numeric range
value:
statusCode: 400
statusMessage: Invalid range
message: Invalid range
data:
error:
code: INVALID_RANGE
message: revenue_min cannot be greater than revenue_max.
details:
parameter: revenue_min,revenue_max
TooManyRequests:
description: 'Rate limit (120 requests per minute per key) or monthly quota exceeded.
`Retry-After` says how many seconds to wait before retrying.
'
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 429
statusMessage: Too Many Requests
message: Too Many Requests
data:
error:
code: QUOTA_EXCEEDED
message: Monthly quota exceeded for this API key.
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 404
statusMessage: Not Found
message: Not Found
data:
error:
code: NOT_FOUND
message: Company not found.
headers:
X-RateLimit-Remaining:
description: Requests left in the current one-minute window.
schema:
type: integer
example: 117
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
example: 30
X-RateLimit-Limit:
description: Requests allowed per minute for this API key.
schema:
type: integer
example: 120
X-RateLimit-Reset:
description: Seconds until the current one-minute window resets.
schema:
type: integer
example: 42
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: 'Optional idempotency key (1-255 characters, e.g. a UUID). Watchlist writes are keyed by KRS,
so repeating the same request — with or without this header — never creates a duplicate entry.
The key is echoed back in the `Idempotency-Key` response header.
'
schema:
type: string
maxLength: 255
example: 3f6c2a4e-8d1b-4c39-9f2e-1a7b5d0e9c41
DryRun:
name: dry_run
in: query
required: false
description: 'When `true`, the request is validated (key, KRS, plan limits) and the response says what
would happen (`would_add` / `would_remove`), but nothing is written and no webhook fires.
'
schema:
type: boolean
default: false
schemas:
ErrorResponse:
type: object
required:
- statusCode
- statusMessage
- message
properties:
statusCode:
type: integer
description: HTTP status code.
statusMessage:
type: string
description: HTTP status text.
message:
type: string
description: Short error summary (same as statusMessage for most errors).
data:
type: object
description: Domain error payload set by the handler.
properties:
message:
type: string
description: Human-readable message (used by 401 responses).
error:
type: object
description: Structured domain error (used by 400/404/429 responses).
properties:
code:
type: string
description: Machine-readable domain error code.
enum:
- INVALID_KRS
- INVALID_NIP
- INVALID_CURSOR
- INVALID_RANGE
- INVALID_PARAMETER
- CONFLICTING_PARAMETERS
- INVALID_BOOLEAN
- INVALID_KEYWORDS
- INVALID_API_KEY
- UNAUTHORIZED
- NOT_FOUND
- QUOTA_EXCEEDED
message:
type: string
details:
type: object
additionalProperties: true
WatchlistAddResponse:
type: object
required:
- krs
- entity_id
- already_following
properties:
krs:
type: string
description: Normalized 10-digit KRS.
example: 0000028860
entity_id:
type: string
format: uuid
description: Internal company identifier.
already_following:
type: boolean
description: True if the company was already on the watchlist before this request.
created_at:
type: string
format: date-time
nullable: true
description: When the watchlist entry was created. Null when already_following is true and the original timestamp is unavailable.
dry_run:
type: boolean
description: Present and `true` only for `dry_run=true` requests — nothing was written.
would_add:
type: boolean
description: Only with `dry_run=true` — whether a real request would add the company.
WatchlistWebhookEvent:
type: object
description: Payload POSTed to your webhook URL when a watched company changes.
required:
- event
- company
- detected_at
properties:
event:
type: string
description: Event type (also sent in the `X-Compabase-Event` header).
enum:
- watchlist.company_changed
- watchlist.board_changed
- watchlist.ownership_changed
- watchlist.status_changed
- watchlist.company_removed_from_registry
- watchlist.financials_updated
- watchlist.filing_overdue
- watchlist.insolvency
- watchlist.court_gazette
- watchlist.secured_liabilities
- watchlist.sanctions
- watchlist.public_tenders
- watchlist.public_aid
- watchlist.licenses
- watchlist.nfz
- watchlist.trademarks
- watchlist.job_offers
- watchlist.contact_changed
- watchlist.company_news
company:
type: object
properties:
entity_id:
type:
- string
- 'null'
format: uuid
name:
type:
- string
- 'null'
krs:
type:
- string
- 'null'
nip:
type:
- string
- 'null'
city:
type:
- string
- 'null'
is_active:
type:
- boolean
- 'null'
revenue_total:
type:
- number
- 'null'
profit_net:
type:
- number
- 'null'
detected_at:
type: string
format: date-time
changes:
type: array
description: Field-level changes, when the event has them.
items:
type: object
properties:
field:
type: string
label:
type: string
old_value: {}
new_value: {}
registry:
type: string
description: Source register for registry events (e.g. KRZ, MSiG, BZP).
delta:
type: number
description: Change of the register counter for registry events.
filing:
type: object
description: Newly filed financial statement (financials_updated).
news:
type: array
description: Newest articles (company_news).
items:
type: object
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
BearerAuth:
type: http
scheme: bearer
x-refined-from:
- compabase-openapi.yaml
- compabase-openapi.yaml