openapi: 3.1.0
info:
  version: 1.0.0
  title: References
  description: |-
    API for CybelAngel's Keywords.
    Authentication uses standard [OAuth2 Bearer Tokens](https://tools.ietf.org/html/rfc6750).

    Here is a simple example of how to fetch such a token with curl:

    ```shell
    curl -X POST https://auth.cybelangel.com/oauth/token -H 'content-type: application/json -d '{"client_id": "client_id", "client_secret": "client_secret", "audience": "https://platform.cybelangel.com/", "grant_type": "client_credentials"}
    ```

    The received access token can then be used as a Bearer token to request our API.
  contact:
    email: support@cybelangel.com
  license:
    url: 'https://cybelangel.com/'
    name: Proprietary
servers:
  - url: 'https://api.cybelangel.com'
paths:
  /v1/keywords:
    get:
      tags:
        - Keywords
      summary: Get Keywords
      description: Get all keywords for organization of authenticated OAuth client token.<br/><br/>Results are sorted alphabetically by the keyword name.
      operationId: get-keywords
      parameters:
        - name: ids
          in: query
          description: Filter keywords by ID. Accepts multiple values (`?ids=<uuid>&ids=<uuid>`).
          required: false
          schema:
            type: array
            title: Ids
            description: Filter keywords by ID. Accepts multiple values (`?ids=<uuid>&ids=<uuid>`).
            default: []
            items:
              type: string
              format: uuid
        - name: name
          in: query
          description: Filter keywords by name.
          required: false
          schema:
            type: string
            title: Name
            description: Filter keywords by name.
        - name: status
          in: query
          description: Filter keywords by status. Accepts multiple values (`?status=pending&status=active`).
          required: false
          schema:
            type: array
            title: Status
            description: Filter keywords by status. Accepts multiple values (`?status=pending&status=active`).
            default: []
            items:
              $ref: '#/components/schemas/KeywordStatus'
        - name: creation_start_date
          in: query
          description: Filter keywords created on or after this date.
          required: false
          schema:
            type: string
            title: Creation Start Date
            description: Filter keywords created on or after this date.
            format: date-time
            examples:
              - '2023-10-05T14:48:00.000Z'
          examples:
            default:
              value: '2023-10-05T14:48:00.000Z'
        - name: creation_end_date
          in: query
          description: Filter keywords created on or before this date.
          required: false
          schema:
            type: string
            title: Creation End Date
            description: Filter keywords created on or before this date.
            format: date-time
            examples:
              - '2023-10-05T14:48:00.000Z'
          examples:
            default:
              value: '2023-10-05T14:48:00.000Z'
        - name: last_modification_start_date
          in: query
          description: Filter keywords last modified on or after this date.
          required: false
          schema:
            type: string
            title: Last Modification Start Date
            description: Filter keywords last modified on or after this date.
            format: date-time
            examples:
              - '2023-10-05T14:48:00.000Z'
          examples:
            default:
              value: '2023-10-05T14:48:00.000Z'
        - name: last_modification_end_date
          in: query
          description: Filter keywords last modified on or before this date.
          required: false
          schema:
            type: string
            title: Last Modification End Date
            description: Filter keywords last modified on or before this date.
            format: date-time
            examples:
              - '2023-10-05T14:48:00.000Z'
          examples:
            default:
              value: '2023-10-05T14:48:00.000Z'
        - name: cursor
          in: query
          description: 'Cursor returned by a previous call to this endpoint. If it is not set, you will get the first page.'
          required: false
          schema:
            type: string
            title: Cursor
            description: 'Cursor returned by a previous call to this endpoint. If it is not set, you will get the first page.'
        - name: workspaces
          in: query
          description: Filter keywords by workspace. Accepts multiple values (`?workspaces=<uuid>&workspaces=<uuid>`).
          required: false
          schema:
            type: array
            title: Workspaces
            description: Filter keywords by workspace. Accepts multiple values (`?workspaces=<uuid>&workspaces=<uuid>`).
            default: []
            items:
              type: string
              format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientKeywordListDTO'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_BadRequestError_'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_UnauthorizedError_'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_ForbiddenAccessError_'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_UnknownError_'
      security:
        - jwt: []
      servers:
        - url: 'https://api.cybelangel.com'
    post:
      tags:
        - Keywords
      summary: Create Keywords
      description: Create a batch of keywords for the organization of the authenticated OAuth client token.<br/><br/>Maximum 10 keywords per request. Keywords are created in "pending" status.
      operationId: create-keywords
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientCreateKeywordsBodyDTO'
      responses:
        '201':
          description: All the keywords were created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientCreateKeywords201ResponseDTO'
        '207':
          description: One or more keywords failed to be created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientCreateKeywords207ResponseDTO'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_BadRequestError_'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_UnauthorizedError_'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_ForbiddenAccessError_'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_UnknownError_'
      security:
        - jwt: []
      servers:
        - url: 'https://api.cybelangel.com'
    patch:
      tags:
        - Keywords
      summary: Update Keywords
      description: Update a batch of keywords for the organization of the authenticated OAuth client token.<br/><br/>Maximum 10 keywords per request. Omitted fields are left unchanged.
      operationId: update-keywords
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientUpdateKeywordsBodyDTO'
      responses:
        '200':
          description: All the keywords were updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientUpdateKeywords200ResponseDTO'
        '207':
          description: One or more keywords failed to be updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientUpdateKeywords207ResponseDTO'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_BadRequestError_'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_UnauthorizedError_'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_ForbiddenAccessError_'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_UnknownError_'
      security:
        - jwt: []
      servers:
        - url: 'https://api.cybelangel.com'
  /v1/keywords/status:
    put:
      tags:
        - Keywords
      summary: Update Keywords Status
      description: Update the status of a batch of keywords for the organization of the authenticated OAuth client token.<br/><br/>Only deactivation ("inactive") is supported. Maximum 10 keywords per request.
      operationId: update-keywords-status
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateKeywordsStatusBodyDTO'
      responses:
        '200':
          description: All the keywords were updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientUpdateKeywords200ResponseDTO'
        '207':
          description: One or more keywords failed to be updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientUpdateKeywords207ResponseDTO'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_BadRequestError_'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_UnauthorizedError_'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_ForbiddenAccessError_'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_UnknownError_'
      security:
        - jwt: []
      servers:
        - url: 'https://api.cybelangel.com'
  /v1/workspaces:
    get:
      tags:
        - Workspaces
      summary: Get Workspaces
      description: Get all workspaces for the organization of the authenticated OAuth client token.
      operationId: get-workspaces
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceListDTO'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_BadRequestError_'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_UnauthorizedError_'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_ForbiddenAccessError_'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse_UnknownError_'
      security:
        - jwt: []
      servers:
        - url: 'https://api.cybelangel.com'
tags:
  - name: Keywords
    description: Manipulate keywords.
  - name: Workspaces
    description: List workspaces.
components:
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    KeywordStatus:
      type: string
      enum:
        - pending
        - active
        - inactive
      title: KeywordStatus
    ClientKeywordListDTO:
      type: object
      title: ClientKeywordListDTO
      additionalProperties: false
      properties:
        items:
          type: array
          title: Items
          description: List of keywords matching the request
          items:
            $ref: '#/components/schemas/ClientKeywordDTO'
        total:
          type: integer
          title: Total
          description: Total number of keywords through all pages
          minimum: 0
        next_cursor:
          title: Next Cursor
          description: Cursor to the next page. You should use this cursor in the "cursor" query parameter to retrieve the next page.
          anyOf:
            - type: string
      required:
        - items
        - total
    ClientKeywordDTO:
      type: object
      title: ClientKeywordDTO
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier of the keyword.
          format: uuid
        name:
          type: string
          title: Name
          description: Name of the keyword.
        type:
          $ref: '#/components/schemas/KeywordType'
          description: Type of the keyword.
        status:
          $ref: '#/components/schemas/KeywordStatus'
          description: Current status of the keyword.
        description:
          type: string
          title: Description
          description: Description of the keyword.
        workspaces:
          type: array
          title: Workspaces
          description: Workspaces the keyword belongs to.
          default: []
          items:
            $ref: '#/components/schemas/WorkspaceDTO'
        creation_date:
          type: string
          title: Creation Date
          description: Date of creation.
          format: date-time
          examples:
            - '2023-10-05T14:48:00.000Z'
        last_modification_date:
          type: string
          title: Last Modification Date
          description: Date of the last modification.
          format: date-time
          examples:
            - '2023-10-05T14:48:00.000Z'
      required:
        - id
        - name
        - type
        - status
        - description
        - creation_date
        - last_modification_date
    KeywordType:
      type: string
      enum:
        - subsidiaries
        - projects
        - domain
        - ip
        - bin
        - vip
        - product
        - misc
      title: KeywordType
    WorkspaceDTO:
      type: object
      title: WorkspaceDTO
      additionalProperties: false
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier of the workspace.
          format: uuid
        name:
          type: string
          title: Name
          description: Name of the workspace.
        description:
          title: Description
          description: Description of the workspace.
          anyOf:
            - type: string
      required:
        - id
        - name
    APIErrorResponse_BadRequestError_:
      type: object
      title: 'APIErrorResponse[BadRequestError]'
      properties:
        error:
          $ref: '#/components/schemas/BadRequestError'
      required:
        - error
    BadRequestError:
      type: object
      title: BadRequestError
      description: User sent a bad request.
      properties:
        message:
          type: string
          title: Message
      required:
        - message
    APIErrorResponse_UnauthorizedError_:
      type: object
      title: 'APIErrorResponse[UnauthorizedError]'
      properties:
        error:
          $ref: '#/components/schemas/UnauthorizedError'
      required:
        - error
    UnauthorizedError:
      type: object
      title: UnauthorizedError
      description: User cannot access some resource.
      properties:
        message:
          type: string
          title: Message
      required:
        - message
    APIErrorResponse_ForbiddenAccessError_:
      type: object
      title: 'APIErrorResponse[ForbiddenAccessError]'
      properties:
        error:
          $ref: '#/components/schemas/ForbiddenAccessError'
      required:
        - error
    ForbiddenAccessError:
      type: object
      title: ForbiddenAccessError
      description: User cannot access some resource.
      properties:
        message:
          type: string
          title: Message
      required:
        - message
    APIErrorResponse_UnknownError_:
      type: object
      title: 'APIErrorResponse[UnknownError]'
      properties:
        error:
          $ref: '#/components/schemas/UnknownError'
      required:
        - error
    UnknownError:
      type: object
      title: UnknownError
      description: 'Unknown error on server-side, please contact support.'
      properties:
        message:
          type: string
          title: Message
      required:
        - message
    ClientCreateKeywordsBodyDTO:
      type: object
      title: ClientCreateKeywordsBodyDTO
      additionalProperties: false
      properties:
        keywords:
          type: array
          title: Keywords
          description: List of keywords to create. Maximum 10 items.
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/ClientCreateKeywordInputDTO'
      required:
        - keywords
    ClientCreateKeywordInputDTO:
      type: object
      title: ClientCreateKeywordInputDTO
      additionalProperties: false
      properties:
        name:
          type: string
          title: Name
          description: Name of the keyword.
          minLength: 1
          maxLength: 500
        type:
          $ref: '#/components/schemas/KeywordType'
          description: Type of the keyword.
        description:
          type: string
          title: Description
          description: Description of the keyword.
          default: ''
        workspaces:
          type: array
          title: Workspaces
          description: Workspaces the keyword belongs to. Required if the organization has workspaces enabled; otherwise defaults to the organization's workspace.
          default: []
          items:
            type: string
            format: uuid
      required:
        - name
    ClientCreateKeywords201ResponseDTO:
      type: object
      title: ClientCreateKeywords201ResponseDTO
      additionalProperties: false
      properties:
        created_keywords:
          type: array
          title: Created Keywords
          description: List of successfully created keywords
          items:
            $ref: '#/components/schemas/ClientKeywordDTO'
        failed_keywords:
          type: array
          title: Failed Keywords
          description: List of keywords that could not be created
          items:
            $ref: '#/components/schemas/FailedToCreateKeywordDTO'
      required:
        - created_keywords
        - failed_keywords
    FailedToCreateKeywordDTO:
      type: object
      title: FailedToCreateKeywordDTO
      properties:
        name:
          type: string
          title: Name
        error_code:
          $ref: '#/components/schemas/CreateKeywordErrorCode'
        error_details:
          title: Error Details
          anyOf:
            - type: string
      required:
        - name
        - error_code
    CreateKeywordErrorCode:
      type: string
      enum:
        - NAME_ALREADY_EXISTS
        - INVALID_NAME
        - INVALID_RULE
        - INFOSTEALER_NOT_AVAILABLE_FOR_TYPE
        - INFOSTEALER_NOT_ACTIVATED
        - INTERNAL_ERROR
      title: CreateKeywordErrorCode
    ClientCreateKeywords207ResponseDTO:
      type: object
      title: ClientCreateKeywords207ResponseDTO
      additionalProperties: false
      properties:
        created_keywords:
          type: array
          title: Created Keywords
          description: List of successfully created keywords
          items:
            $ref: '#/components/schemas/ClientKeywordDTO'
        failed_keywords:
          type: array
          title: Failed Keywords
          description: List of keywords that could not be created
          items:
            $ref: '#/components/schemas/FailedToCreateKeywordDTO'
      required:
        - created_keywords
        - failed_keywords
    ClientUpdateKeywordsBodyDTO:
      type: object
      title: ClientUpdateKeywordsBodyDTO
      additionalProperties: false
      properties:
        keywords:
          type: array
          title: Keywords
          description: List of keywords to update. Maximum 10 items.
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/ClientUpdateKeywordInputDTO'
      required:
        - keywords
    ClientUpdateKeywordInputDTO:
      type: object
      title: ClientUpdateKeywordInputDTO
      additionalProperties: false
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier of the keyword to update.
          format: uuid
        type:
          description: Type of the keyword.
          anyOf:
            - $ref: '#/components/schemas/KeywordType'
        description:
          title: Description
          description: Description of the keyword.
          anyOf:
            - type: string
        workspaces:
          title: Workspaces
          description: Workspaces the keyword belongs to. Required if the organization has workspaces enabled; otherwise defaults to the organization's workspace.
          anyOf:
            - type: array
              minItems: 1
              items:
                type: string
                format: uuid
      required:
        - id
    ClientUpdateKeywords200ResponseDTO:
      type: object
      title: ClientUpdateKeywords200ResponseDTO
      additionalProperties: false
      properties:
        updated_keywords:
          type: array
          title: Updated Keywords
          description: List of successfully updated keywords
          items:
            $ref: '#/components/schemas/ClientKeywordDTO'
        failed_keywords:
          type: array
          title: Failed Keywords
          description: List of keywords that could not be updated
          items:
            $ref: '#/components/schemas/FailedToUpdateKeywordDTO'
      required:
        - updated_keywords
        - failed_keywords
    FailedToUpdateKeywordDTO:
      type: object
      title: FailedToUpdateKeywordDTO
      properties:
        id:
          type: string
          title: Id
          format: uuid
        error_code:
          $ref: '#/components/schemas/UpdateKeywordErrorCode'
        error_details:
          title: Error Details
          anyOf:
            - type: string
      required:
        - id
        - error_code
    UpdateKeywordErrorCode:
      type: string
      enum:
        - NOT_FOUND
        - NAME_ALREADY_EXISTS
        - INVALID_NAME
        - INVALID_RULE
        - INFOSTEALER_NOT_AVAILABLE_FOR_TYPE
        - INFOSTEALER_NOT_ACTIVATED
        - INTERNAL_ERROR
      title: UpdateKeywordErrorCode
    ClientUpdateKeywords207ResponseDTO:
      type: object
      title: ClientUpdateKeywords207ResponseDTO
      additionalProperties: false
      properties:
        updated_keywords:
          type: array
          title: Updated Keywords
          description: List of successfully updated keywords
          items:
            $ref: '#/components/schemas/ClientKeywordDTO'
        failed_keywords:
          type: array
          title: Failed Keywords
          description: List of keywords that could not be updated
          items:
            $ref: '#/components/schemas/FailedToUpdateKeywordDTO'
      required:
        - updated_keywords
        - failed_keywords
    UpdateKeywordsStatusBodyDTO:
      type: object
      title: UpdateKeywordsStatusBodyDTO
      additionalProperties: false
      properties:
        keywords:
          type: array
          title: Keywords
          description: List of keywords whose status to update. Maximum 10 items.
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/UpdateKeywordStatusInputDTO'
      required:
        - keywords
    UpdateKeywordStatusInputDTO:
      type: object
      title: UpdateKeywordStatusInputDTO
      additionalProperties: false
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier of the keyword to update.
          format: uuid
        status:
          const: inactive
          title: Status
          description: New status of the keyword. Only "inactive" (deactivation) is accepted.
      required:
        - id
        - status
    WorkspaceListDTO:
      type: object
      title: WorkspaceListDTO
      additionalProperties: false
      properties:
        items:
          type: array
          title: Items
          description: List of workspaces matching the request
          items:
            $ref: '#/components/schemas/WorkspaceDTO'
        total:
          type: integer
          title: Total
          description: Total number of workspaces
          minimum: 0
      required:
        - items
        - total