CloudTruth Log Destinations API

openapi: 3.2.0
info:
  title: CloudTruth Management Log Destinations API
  version: v1
  description: CloudTruth centralizes your configuration parameters and secrets making them easier to manage and use as a team.
  contact:
    name: CloudTruth Support
    email: support@cloudtruth.com
tags:
- name: log-destinations
paths:
  /api/v1/log-destinations/:
    get:
      operationId: log_destinations_list
      description: 'SOC 2 SIEM-export configuration endpoint. Admin-only.


        The /test action sends a single synthetic record to the configured

        destination — useful for the UI''s "Test connection" button without

        waiting for a real audit event to flow through the drain.


        Mike''s PR #3798 review item #20 hardened this in three ways:

        1. Per-destination cooldown (default 30s, settings-tunable)

        prevents an admin from rate-amplifying the internal probe

        described in the review note. Returns 429 when active.

        2. A structured audit log entry tagged

        ``event.action="log_destination_tested"`` fires for every

        attempt, including 429s. Routed via the app log feed which

        feeds the SIEM by default — equivalent to an in-DB audit row

        for SOC 2 evidence purposes.

        3. The synchronous ``send_batch`` is now wrapped by review

        item #2''s ``recheck_https_url`` (already merged) so the

        attempted target is re-resolved and validated immediately

        before connect, closing the DNS-rebinding race window.'
      parameters:
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      tags:
      - log-destinations
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedLogDestinationsList'
          description: ''
      summary: Log destinations list
      x-summary-source: derived
    post:
      operationId: log_destinations_create
      description: 'SOC 2 SIEM-export configuration endpoint. Admin-only.


        The /test action sends a single synthetic record to the configured

        destination — useful for the UI''s "Test connection" button without

        waiting for a real audit event to flow through the drain.


        Mike''s PR #3798 review item #20 hardened this in three ways:

        1. Per-destination cooldown (default 30s, settings-tunable)

        prevents an admin from rate-amplifying the internal probe

        described in the review note. Returns 429 when active.

        2. A structured audit log entry tagged

        ``event.action="log_destination_tested"`` fires for every

        attempt, including 429s. Routed via the app log feed which

        feeds the SIEM by default — equivalent to an in-DB audit row

        for SOC 2 evidence purposes.

        3. The synchronous ``send_batch`` is now wrapped by review

        item #2''s ``recheck_https_url`` (already merged) so the

        attempted target is re-resolved and validated immediately

        before connect, closing the DNS-rebinding race window.'
      tags:
      - log-destinations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogDestinations'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LogDestinations'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LogDestinations'
        required: true
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogDestinations'
          description: ''
      summary: Log destinations create
      x-summary-source: derived
  /api/v1/log-destinations/{id}/:
    get:
      operationId: log_destinations_retrieve
      description: 'SOC 2 SIEM-export configuration endpoint. Admin-only.


        The /test action sends a single synthetic record to the configured

        destination — useful for the UI''s "Test connection" button without

        waiting for a real audit event to flow through the drain.


        Mike''s PR #3798 review item #20 hardened this in three ways:

        1. Per-destination cooldown (default 30s, settings-tunable)

        prevents an admin from rate-amplifying the internal probe

        described in the review note. Returns 429 when active.

        2. A structured audit log entry tagged

        ``event.action="log_destination_tested"`` fires for every

        attempt, including 429s. Routed via the app log feed which

        feeds the SIEM by default — equivalent to an in-DB audit row

        for SOC 2 evidence purposes.

        3. The synchronous ``send_batch`` is now wrapped by review

        item #2''s ``recheck_https_url`` (already merged) so the

        attempted target is re-resolved and validated immediately

        before connect, closing the DNS-rebinding race window.'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
          description: Primary key for log destination.
        required: true
      tags:
      - log-destinations
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogDestinations'
          description: ''
      summary: Log destinations retrieve
      x-summary-source: derived
    put:
      operationId: log_destinations_update
      description: 'SOC 2 SIEM-export configuration endpoint. Admin-only.


        The /test action sends a single synthetic record to the configured

        destination — useful for the UI''s "Test connection" button without

        waiting for a real audit event to flow through the drain.


        Mike''s PR #3798 review item #20 hardened this in three ways:

        1. Per-destination cooldown (default 30s, settings-tunable)

        prevents an admin from rate-amplifying the internal probe

        described in the review note. Returns 429 when active.

        2. A structured audit log entry tagged

        ``event.action="log_destination_tested"`` fires for every

        attempt, including 429s. Routed via the app log feed which

        feeds the SIEM by default — equivalent to an in-DB audit row

        for SOC 2 evidence purposes.

        3. The synchronous ``send_batch`` is now wrapped by review

        item #2''s ``recheck_https_url`` (already merged) so the

        attempted target is re-resolved and validated immediately

        before connect, closing the DNS-rebinding race window.'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
          description: Primary key for log destination.
        required: true
      tags:
      - log-destinations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogDestinations'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LogDestinations'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LogDestinations'
        required: true
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogDestinations'
          description: ''
      summary: Log destinations update
      x-summary-source: derived
    patch:
      operationId: log_destinations_partial_update
      description: 'SOC 2 SIEM-export configuration endpoint. Admin-only.


        The /test action sends a single synthetic record to the configured

        destination — useful for the UI''s "Test connection" button without

        waiting for a real audit event to flow through the drain.


        Mike''s PR #3798 review item #20 hardened this in three ways:

        1. Per-destination cooldown (default 30s, settings-tunable)

        prevents an admin from rate-amplifying the internal probe

        described in the review note. Returns 429 when active.

        2. A structured audit log entry tagged

        ``event.action="log_destination_tested"`` fires for every

        attempt, including 429s. Routed via the app log feed which

        feeds the SIEM by default — equivalent to an in-DB audit row

        for SOC 2 evidence purposes.

        3. The synchronous ``send_batch`` is now wrapped by review

        item #2''s ``recheck_https_url`` (already merged) so the

        attempted target is re-resolved and validated immediately

        before connect, closing the DNS-rebinding race window.'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
          description: Primary key for log destination.
        required: true
      tags:
      - log-destinations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedLogDestinations'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedLogDestinations'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedLogDestinations'
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogDestinations'
          description: ''
      summary: Log destinations partial update
      x-summary-source: derived
    delete:
      operationId: log_destinations_destroy
      description: 'SOC 2 SIEM-export configuration endpoint. Admin-only.


        The /test action sends a single synthetic record to the configured

        destination — useful for the UI''s "Test connection" button without

        waiting for a real audit event to flow through the drain.


        Mike''s PR #3798 review item #20 hardened this in three ways:

        1. Per-destination cooldown (default 30s, settings-tunable)

        prevents an admin from rate-amplifying the internal probe

        described in the review note. Returns 429 when active.

        2. A structured audit log entry tagged

        ``event.action="log_destination_tested"`` fires for every

        attempt, including 429s. Routed via the app log feed which

        feeds the SIEM by default — equivalent to an in-DB audit row

        for SOC 2 evidence purposes.

        3. The synchronous ``send_batch`` is now wrapped by review

        item #2''s ``recheck_https_url`` (already merged) so the

        attempted target is re-resolved and validated immediately

        before connect, closing the DNS-rebinding race window.'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
          description: Primary key for log destination.
        required: true
      tags:
      - log-destinations
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '204':
          description: No response body
      summary: Log destinations destroy
      x-summary-source: derived
  /api/v1/log-destinations/{id}/test/:
    post:
      operationId: log_destinations_test_create
      description: 'SOC 2 SIEM-export configuration endpoint. Admin-only.


        The /test action sends a single synthetic record to the configured

        destination — useful for the UI''s "Test connection" button without

        waiting for a real audit event to flow through the drain.


        Mike''s PR #3798 review item #20 hardened this in three ways:

        1. Per-destination cooldown (default 30s, settings-tunable)

        prevents an admin from rate-amplifying the internal probe

        described in the review note. Returns 429 when active.

        2. A structured audit log entry tagged

        ``event.action="log_destination_tested"`` fires for every

        attempt, including 429s. Routed via the app log feed which

        feeds the SIEM by default — equivalent to an in-DB audit row

        for SOC 2 evidence purposes.

        3. The synchronous ``send_batch`` is now wrapped by review

        item #2''s ``recheck_https_url`` (already merged) so the

        attempted target is re-resolved and validated immediately

        before connect, closing the DNS-rebinding race window.'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
          description: Primary key for log destination.
        required: true
      tags:
      - log-destinations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogDestinations'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LogDestinations'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LogDestinations'
        required: true
      security:
      - JWTAuth: []
      - ApiKeyAuth: []
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogDestinations'
          description: ''
      summary: Log destinations test create
      x-summary-source: derived
components:
  schemas:
    LogDestinations:
      type: object
      description: 'Per-org log destination CRUD.


        Per-type config (api_key, token, collector_url, etc.) is submitted

        inside ``configuration``. Sensitive keys are encrypted at rest via

        ``LogDestination.SENSITIVE_CONFIG_KEYS`` and masked on read by

        ``to_representation``.'
      properties:
        url:
          type: string
          format: uri
          readOnly: true
        id:
          type: string
          format: uuid
          readOnly: true
          description: Primary key for log destination.
        name:
          type: string
          description: Customer-chosen name for this destination.
        type:
          allOf:
          - $ref: '#/components/schemas/LogDestinationsTypeEnum'
          description: 'The sink type (Datadog, etc.).


            * `datadog` - Datadog Logs

            * `splunk_hec` - Splunk HEC

            * `sumo_logic` - Sumo Logic HTTP Source

            * `generic_https` - Generic HTTPS Webhook'
        enabled:
          type: boolean
          default: true
        configuration: {}
        last_attempt_at:
          type: string
          format: date-time
          readOnly: true
        last_success_at:
          type: string
          format: date-time
          readOnly: true
        last_error:
          readOnly: true
        consecutive_failures:
          type: integer
          readOnly: true
        total_records_delivered:
          type: integer
          readOnly: true
        gap_skipped_count:
          type: integer
          readOnly: true
        cursor_lag_seconds:
          type: integer
          description: Age (in seconds) of the oldest audit record waiting to be delivered. 0 means caught up — no pending records. Growing values indicate the drain is falling behind.
          readOnly: true
      required:
      - configuration
      - consecutive_failures
      - cursor_lag_seconds
      - gap_skipped_count
      - id
      - last_attempt_at
      - last_error
      - last_success_at
      - name
      - total_records_delivered
      - type
      - url
    LogDestinationsTypeEnum:
      enum:
      - datadog
      - splunk_hec
      - sumo_logic
      - generic_https
      type: string
      description: '* `datadog` - Datadog Logs

        * `splunk_hec` - Splunk HEC

        * `sumo_logic` - Sumo Logic HTTP Source

        * `generic_https` - Generic HTTPS Webhook'
    PaginatedLogDestinationsList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/LogDestinations'
    PatchedLogDestinations:
      type: object
      description: 'Per-org log destination CRUD.


        Per-type config (api_key, token, collector_url, etc.) is submitted

        inside ``configuration``. Sensitive keys are encrypted at rest via

        ``LogDestination.SENSITIVE_CONFIG_KEYS`` and masked on read by

        ``to_representation``.'
      properties:
        url:
          type: string
          format: uri
          readOnly: true
        id:
          type: string
          format: uuid
          readOnly: true
          description: Primary key for log destination.
        name:
          type: string
          description: Customer-chosen name for this destination.
        type:
          allOf:
          - $ref: '#/components/schemas/LogDestinationsTypeEnum'
          description: 'The sink type (Datadog, etc.).


            * `datadog` - Datadog Logs

            * `splunk_hec` - Splunk HEC

            * `sumo_logic` - Sumo Logic HTTP Source

            * `generic_https` - Generic HTTPS Webhook'
        enabled:
          type: boolean
          default: true
        configuration: {}
        last_attempt_at:
          type: string
          format: date-time
          readOnly: true
        last_success_at:
          type: string
          format: date-time
          readOnly: true
        last_error:
          readOnly: true
        consecutive_failures:
          type: integer
          readOnly: true
        total_records_delivered:
          type: integer
          readOnly: true
        gap_skipped_count:
          type: integer
          readOnly: true
        cursor_lag_seconds:
          type: integer
          description: Age (in seconds) of the oldest audit record waiting to be delivered. 0 means caught up — no pending records. Growing values indicate the drain is falling behind.
          readOnly: true
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: Authorization
      type: apiKey
      description: "\nUse your CloudTruth API Key to authenticate to the API.  You can get\nan API Key by creating a Service Account.  During setup of the Service\nAccount you will generate a long-lived API key intended for use by automation\nand API clients.  Access through the service account will be audited separately\nfrom any other user.\n\nIf you are just trying to use the API in a normal workflow, this is likely the\nauthentication mechanism you want to use.\n\nTo use the API Key, place your API Key in the Authorization header as 'Api-Key APIKEY', where\nAPIKEY is your CloudTruth API Key.  For example:\n\n    Authorization: Api-Key fskur.ghlsiudhrg84so938r5u\n        "
    JWTAuth:
      in: header
      name: Authorization
      type: apiKey
      description: "\nUse your JWT to authenticate to the API.  This is how the CloudTruth\nWeb UI authenticates to the backend.  It requires a user to have already logged in\nand gotten a JWT from the login process.  This is usually done by an Auth0 authentication\nflow from one of the Auth0 javascript libraries.  Alternatively, you can pull the\nJWT from your browser if you have a logged in session with the CloudTruth UI.\n\nThis authentication mechanism is intended for deeper integrations into the CloudTruth\nsystem, where you want to handle the user logins directly in your application.  For\nnormal API use, you likely want the Api-Key authentication header and not this one.\n\nTo use the JWT, place your JWT in the Authorization header as 'Bearer JWT', where\nJWT is your JWT.  For example:\n\n    Authorization: Bearer eyJhbGciOiJIkuydfy.eyJzdWIiOiIxMjM....\n        "
    tokenAuth:
      type: http
      scheme: bearer
externalDocs:
  url: https://docs.cloudtruth.com/