openapi: 3.0.3
info:
  title: Stellar Cyber Open XDR Alerts Watchlists API
  description: The Stellar Cyber REST API provides programmatic access to the Open XDR platform, enabling automation of security operations including case management, tenant administration, connector management, alert handling, query operations, user management, watchlists, sensors, and security event management.
  version: '6.3'
  contact:
    name: Stellar Cyber Support
    url: https://stellarcyber.zendesk.com
  license:
    name: Proprietary
    url: https://stellarcyber.ai/terms/
servers:
- url: https://{platformHostname}/connect/api/v1
  description: Stellar Cyber Platform API
  variables:
    platformHostname:
      description: Your Stellar Cyber platform hostname
      default: your-platform.stellarcyber.ai
security:
- bearerAuth: []
tags:
- name: Watchlists
  description: Watchlist creation and management
paths:
  /watchlists:
    get:
      operationId: listWatchlists
      summary: List Watchlists
      description: Retrieve all configured watchlists.
      tags:
      - Watchlists
      responses:
        '200':
          description: List of watchlists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistsListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWatchlist
      summary: Create Watchlist
      description: Create a new watchlist for tracking threat indicators.
      tags:
      - Watchlists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWatchlistRequest'
      responses:
        '201':
          description: Watchlist created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /watchlists/{watchlistId}:
    delete:
      operationId: deleteWatchlist
      summary: Delete Watchlist
      description: Delete a watchlist.
      tags:
      - Watchlists
      parameters:
      - $ref: '#/components/parameters/WatchlistId'
      responses:
        '204':
          description: Watchlist deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    WatchlistsListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Watchlist'
        total:
          type: integer
    CreateWatchlistRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        description:
          type: string
        entries:
          type: array
          items:
            type: string
    Watchlist:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        entries:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        code:
          type: integer
  responses:
    Unauthorized:
      description: Authentication required or token expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    WatchlistId:
      name: watchlistId
      in: path
      required: true
      description: Unique identifier for the watchlist
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from /access_token endpoint. Tokens expire after 10 minutes. API keys can also be used as Bearer tokens for the /access_token call.