Compabase Watchlist API

The Watchlist API from Compabase — 2 operation(s) for watchlist.

GitHub OpenAPI

Operations 3

GET /watchlist List watchlist #
POST /watchlist/krs/{krs} Add company to watchlist #
DELETE /watchlist/krs/{krs} Remove company from watchlist #

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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/compabase:compabase-watchlist-api"
All apis
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.

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

compabase-watchlist-api-openapi.yml Raw ↑
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