> ## Documentation Index > Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt > Use this file to discover all available pages before exploring further. # List detection rule proposals > Retrieve all detection rule proposals for the organization. ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json get /api/detection-rules/proposals openapi: 3.1.0 info: title: Cotool API version: 1.0.0 description: >- # Cotool API Documentation The Cotool API allows you to interact with the Cotool platform programmatically, enabling you to build powerful integrations and automate your workflows. ## Getting an API Key Follow these steps to generate your API key: 1. **Log in** to the Cotool web interface 2. **Navigate** to `/settings/api-keys` 3. **Click** "Generate Key" 4. **Copy and store** your API key securely ⚠️ *It won't be shown again* ## API Key Authentication For programmatic access and integrations, use your API key with the Authorization header: ```http Authorization: Bearer your_api_key_here ``` ```bash curl -X GET "https://app.cotool.ai/api/endpoint" \ -H "Authorization: Bearer your_api_key_here" \ -H "Content-Type: application/json" ``` servers: - url: https://app.cotool.ai description: Production server security: - ApiKeyAuth: [] paths: /api/detection-rules/proposals: get: tags: - Detection Rules summary: List detection rule proposals description: Retrieve all detection rule proposals for the organization. parameters: - in: query name: status description: Filter by status (comma-separated for multiple) schema: type: string description: Filter by status (comma-separated for multiple) - in: query name: platform description: Filter by SIEM platform schema: type: string description: Filter by SIEM platform - in: query name: limit description: Max results to return (default 50) schema: type: string description: Max results to return (default 50) - in: query name: offset description: Offset for pagination schema: type: string description: Offset for pagination - in: query name: includeDismissed description: Include dismissed proposals (true/false, default false) schema: type: string description: Include dismissed proposals (true/false, default false) responses: '200': description: Successful response content: application/json: schema: type: object properties: proposals: type: array items: type: object properties: id: type: string format: uuid organizationId: type: string format: uuid name: type: string description: type: string query: type: string siemPlatform: type: string reasoning: type: string description: Why this detection is valuable for this environment mitreTechniqueIds: type: array items: type: string mitreTechniqueNames: type: array items: type: string mitreTacticIds: type: array items: type: string dataSourcesRequired: type: array items: type: string suggestedTuning: type: - object - 'null' properties: exclusions: type: array items: type: string description: >- Common exclusions to reduce noise (service accounts, automated jobs, etc.) thresholds: type: array items: type: string description: Tunable threshold parameters expectedVolume: type: string description: Expected alert volume when well-tuned grade: type: - integer - 'null' minimum: 0 maximum: 20 description: Quality grade assigned by the agent (0-20) gradeReason: type: - string - 'null' description: Explanation of why this grade was assigned testResultsSummary: type: - string - 'null' description: Summary of test query results from the agent status: type: string enum: - proposed - validated - validation_failed - published - pr_created - merged - rejected - dismissed validationResult: type: - object - 'null' properties: valid: type: boolean error: type: string details: type: object properties: syntaxOk: type: boolean executionOk: type: boolean resultCount: type: number executionTimeMs: type: number required: - syntaxOk - executionOk required: - valid - details volumeCheckResult: type: - object - 'null' properties: checkedAt: type: string format: date-time description: When the volume check was performed rowCount: type: number description: Total matching rows in the sample window bytesScanned: type: number description: Bytes scanned by the query (platform-dependent) executionTimeMs: type: number description: Query execution time in milliseconds timeRangeHours: type: number description: Time range of the sample (typically 1 hour) sampleResults: type: array items: type: object additionalProperties: {} description: Actual sample rows returned (up to 10) querySnapshot: type: string description: >- The query that was tested (detect if edited since) bestEstimate: type: object properties: count: type: number minimum: 0 description: Estimated hit count in the sample window timeRangeHours: type: number minimum: 1 description: Time window in hours used for the estimate basis: type: string enum: - estimated_detection_noisiness - sample_query_results description: Source category quality: type: string enum: - authoritative - sampled - fallback description: Estimate confidence source: type: string description: Platform-specific source identifier required: - count - timeRangeHours - basis - quality description: >- Single best platform-specific estimate used to display hits/hr required: - checkedAt - rowCount - executionTimeMs - timeRangeHours detectionIntent: type: - object - 'null' properties: methodLabel: type: string description: >- Human-readable method/type label e.g. Threshold, Anomaly Detection rationale: type: string description: Why this method was chosen for this detection confidence: type: string enum: - high - medium - low description: Agent confidence in method choice keyKnobs: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean description: >- Key parameters for display e.g. evaluationWindowSeconds, aggregation required: - methodLabel platformConfig: anyOf: - oneOf: - type: object properties: version: type: number const: 1 platform: type: string const: datadog queries: type: array items: type: object properties: name: type: string query: type: string aggregation: type: string enum: - count - cardinality - sum - max - new_value - geo_data - event_count - none dataSource: type: string enum: - logs - audit - spans default: logs groupByFields: type: array items: type: string distinctFields: type: array items: type: string required: - name - query - aggregation - dataSource minItems: 1 cases: type: array items: type: object properties: status: type: string enum: - info - low - medium - high - critical condition: type: string name: type: string required: - status - condition minItems: 1 options: type: object properties: detectionMethod: type: string enum: - threshold - new_value - anomaly_detection - impossible_travel evaluationWindow: anyOf: - type: number const: 0 - type: number const: 60 - type: number const: 300 - type: number const: 600 - type: number const: 900 - type: number const: 1800 - type: number const: 3600 - type: number const: 7200 - type: number const: 10800 - type: number const: 21600 - type: number const: 43200 - type: number const: 86400 keepAlive: anyOf: - type: number const: 0 - type: number const: 60 - type: number const: 300 - type: number const: 600 - type: number const: 900 - type: number const: 1800 - type: number const: 3600 - type: number const: 7200 - type: number const: 10800 - type: number const: 21600 - type: number const: 43200 - type: number const: 86400 description: >- Seconds signal stays open after last match maxSignalDuration: anyOf: - type: number const: 0 - type: number const: 60 - type: number const: 300 - type: number const: 600 - type: number const: 900 - type: number const: 1800 - type: number const: 3600 - type: number const: 7200 - type: number const: 10800 - type: number const: 21600 - type: number const: 43200 - type: number const: 86400 description: Max seconds a signal stays open decreaseCriticalityBasedOnEnv: type: boolean required: - detectionMethod - evaluationWindow - keepAlive - maxSignalDuration isEnabled: type: boolean description: >- Deploy rule in enabled (true) or disabled (false) state. Defaults to true. required: - version - platform - queries - cases - options - type: object additionalProperties: {} description: >- Legacy or unknown shape; parse with safeParse when reading - type: 'null' prUrl: type: - string - 'null' prMergedAt: type: - string - 'null' format: date-time publishMethod: type: - string - 'null' enum: - api - pr - null description: How the detection was published (api or pr) publishedAt: type: - string - 'null' format: date-time publishedRuleId: type: - string - 'null' description: >- ID of the rule in the SIEM platform after API publish jobRunId: type: - string - 'null' format: uuid dismissedReason: type: - string - 'null' dismissedBy: type: - string - 'null' format: uuid dismissedAt: type: - string - 'null' format: date-time publishingStartedAt: type: - string - 'null' format: date-time description: >- When Push to Git was initiated (null = not publishing) createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - organizationId - name - description - query - siemPlatform - reasoning - mitreTechniqueIds - mitreTechniqueNames - mitreTacticIds - dataSourcesRequired - suggestedTuning - status - validationResult - volumeCheckResult - prUrl - prMergedAt - publishMethod - publishedAt - publishedRuleId - jobRunId - dismissedReason - dismissedBy - dismissedAt - publishingStartedAt - createdAt - updatedAt total: type: number required: - proposals - total '400': description: Bad request — input validation failed or the request was malformed content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized — missing or invalid API key / session content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden — the authenticated user lacks the required permissions content: application/json: schema: $ref: '#/components/schemas/PermissionError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: shell label: cURL source: |- curl -X GET "https://app.cotool.ai/api/detection-rules/proposals" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" components: schemas: ValidationError: type: object properties: error: type: string description: Error message describing what went wrong issues: type: array description: >- Detailed validation issues, present when request or response schema validation fails items: type: object additionalProperties: true required: - error Error: type: object properties: error: type: string description: Error message describing what went wrong required: - error PermissionError: type: object properties: error: type: string description: Error message describing what went wrong missingPerms: type: array description: Permissions the authenticated user is missing for this operation items: type: string required: - error securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- API Key authentication for programmatic access. Include your API key in the Authorization header as: `Bearer your_api_key_here` ````