---
title: "Add a detection library entry"
method: POST
path: "/api/detection-library/{slug}/add"
tags: ["Detections"]
---

# Add a detection library entry

`POST /api/detection-library/{slug}/add`

## Request

- Base URL: `https://app.cotool.ai`
- URL: `https://app.cotool.ai/api/detection-library/{slug}/add`
- Auth: HTTP bearer

Creates an org-owned detection from the entry, publishes its notebook as version 1, and enables the entry's default schedule.

## Path parameters

- `slug` string, required

## Response `200`

Successful response

- object
  - `calibration` object, nullable
    - `state` 'calibrating' | 'live' | 'paused', required
    - `attempt` object, nullable, required
      - `id` string, uuid, required
      - `organizationId` string, uuid, required
      - `detectionId` string, uuid, required
      - `reason` 'library_add' | 'drift' | 'retry' | 'recalibrate' | 'approved_change' | 'agent_authored', required
      - `startedAt` string, date-time, required
      - `deadlineAt` string, date-time, required
      - `endedAt` string, date-time, nullable, required
      - `outcome` 'live' | 'paused' | 'overridden' | 'cancelled' | 'null', nullable, required
      - `pauseReason` 'still_noisy' | 'insufficient_data' | 'approval_required' | 'manual' | 'null', nullable, required
      - `evidenceSince` string, date-time, required
      - `latestEvaluation` object, nullable, required
        - `versionId` string, uuid, required
        - `result` 'passing' | 'noisy' | 'incomplete', required
        - `usableCoverageHours` number, required
        - `backtestCoverageHours` number, required
        - `latestDailyFindings` integer, nullable, required
        - `maxDailyFindings` integer, required
        - `source` 'backtest' | 'observation' | 'mixed' | 'null', nullable, required
        - `evaluatedAt` string, date-time, required
      - `activeRunId` string, uuid, nullable, required
      - `lastRunId` string, uuid, nullable, required
      - `agentRunsUsed` integer, required
      - `deepRunAt` string, date-time, nullable, required
      - `correctionRequestedAt` string, date-time, nullable, required
      - `lastCorrectionRunAt` string, date-time, nullable, required
      - `backtestSupported` boolean, nullable, required
      - `retryNumber` integer, required
      - `retryAt` string, date-time, nullable, required
      - `drift` object, nullable, required
        - `recentAlerts` integer, required
        - `usualMaxDailyAlerts` integer, required
    - `step` union, required
      - object
        - `kind` 'promote', required
      - object
        - `kind` 'pause', required
        - `reason` 'still_noisy' | 'insufficient_data' | 'approval_required', required
      - object
        - `kind` 'backtest', required
      - object
        - `kind` 'agent', required
        - `run` 'initial' | 'deep' | 'correction', required
      - object
        - `kind` 'wait', required
        - `for` 'agent' | 'deep_run' | 'correction' | 'evidence', required
        - `until` string, date-time, nullable, required
    - `currentVersionId` string, uuid, nullable, required
    - `pendingProposalId` string, uuid, nullable, required
  - `id` string, uuid, required
  - `chatId` string, uuid, nullable, required: Caller-owned editor chat on detail responses; always null in catalog rows
  - `revision` string, required
  - `name` string, nullable, required
  - `summary` string, nullable, required: 1–3 sentence plain-prose headline of what the detection is meant to detect. No bullet lists.
  - `howItWorks` string, nullable, required: How the detection works, as operational GitHub-flavored markdown: typically two or three bullets covering the signal it watches and the condition that fires
  - `toolNames` string[], required
  - `mitreTechniqueIds` string[], required
  - `metadataStatus` 'pending' | 'ready' | 'failed', required
  - `librarySlug` string, nullable, required: Library entry this detection was installed from, when any: a detection library slug for alert detections, a streaming detection library slug for streaming detections
  - `outputKind` 'alerts' | 'signals', required
  - `executionMode` 'batch' | 'streaming', required
  - `managed` boolean, required: Cotool owns the logic and keeps it current with its library entry; the org can enable or disable it but not edit it
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `publishedVersionId` string, uuid, nullable, required
  - `recentHits` object[], required
    - `id` string, uuid, required
    - `executionId` string, uuid, required
    - `entity` string, required
    - `entityType` string, nullable, required
    - `severity` 'low' | 'medium' | 'high' | 'critical' | 'null', nullable, required
    - `headline` string, nullable, required
    - `summary` string, nullable, required
    - `evidence` object, required: The emitted row backing this hit
    - `closedAt` string, date-time, nullable, required
    - `lastSeenAt` string, date-time, required
    - `lastSeenExecutionId` string, uuid, nullable, required
    - `seenCount` integer, required
    - `linkedAlert` object, nullable, required
      - `id` string, uuid, required
      - `displayId` string, required
      - `status` 'open' | 'in_progress' | 'escalated' | 'closed_true_positive' | 'closed_false_positive' | 'closed_true_positive_benign' | 'dismissed' | 'duplicate' | 'expired', required: Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists.
      - `derivedDisposition` 'true_positive' | 'false_positive' | 'true_positive_benign' | 'null', nullable, required: Verdict credited to this hit. For an alert archived as a duplicate this is the canonical alert's verdict.
      - `assignedAgent` object, nullable, required
        - `id` string, uuid, required
        - `name` string, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `feedback` object, required
    - `detectionId` string, uuid, required
    - `windowDays` integer, required
    - `dispositions` object, required: Alert verdicts credited to the detection. Alerts archived as duplicates inherit the verdict of their canonical alert.
      - `truePositive` integer, required
      - `falsePositive` integer, required
      - `benign` integer, required
    - `statuses` object, required
      - `open` integer, required
      - `inProgress` integer, required
      - `escalated` integer, required
      - `duplicate` integer, required: Duplicates whose canonical alert has no verdict yet. Once the canonical alert is dispositioned the duplicate moves into that disposition count.
      - `dismissed` integer, required
      - `expired` integer, required
    - `precision` object, required
      - `value` number, nullable, required
      - `numerator` integer, required
      - `denominator` integer, required
    - `versions` object[], required
      - `versionId` string, uuid, required
      - `version` integer, required
      - `dispositions` object, required: Alert verdicts credited to the detection. Alerts archived as duplicates inherit the verdict of their canonical alert.
        - `truePositive` integer, required
        - `falsePositive` integer, required
        - `benign` integer, required
      - `precision` object, required
        - `value` number, nullable, required
        - `numerator` integer, required
        - `denominator` integer, required
    - `falsePositiveEntities` object[], required
      - `entity` string, required
      - `entityType` string, nullable, required
      - `count` integer, required
    - `actorSplit` object, required
      - `human` object, required: Alert verdicts credited to the detection. Alerts archived as duplicates inherit the verdict of their canonical alert.
        - `truePositive` integer, required
        - `falsePositive` integer, required
        - `benign` integer, required
      - `agent` object, required: Alert verdicts credited to the detection. Alerts archived as duplicates inherit the verdict of their canonical alert.
        - `truePositive` integer, required
        - `falsePositive` integer, required
        - `benign` integer, required
    - `scheduledExecutions` object, required
      - `total` integer, required
      - `succeeded` integer, required
      - `failed` integer, required
      - `interrupted` integer, required
      - `running` integer, required
      - `successRate` number, nullable, required
      - `averageRuntimeMs` number, nullable, required
      - `errorCount` integer, required
      - `recentErrors` object[], required
        - `message` string, required
        - `count` integer, required
        - `lastOccurredAt` string, date-time, required
      - `lastScheduledRunAt` string, date-time, nullable, required
      - `lastFinishedStatus` 'succeeded' | 'failed' | 'interrupted' | 'null', nullable, required
    - `volume` object, required
      - `hits` integer, required
      - `alerts` integer, required
      - `lastResultAt` string, date-time, nullable, required
      - `lastAlertAt` string, date-time, nullable, required
    - `everEscalated` integer, required
    - `meanTimeToDispositionSeconds` number, nullable, required
  - `retirement` object, nullable: Set when the detection is retired
    - `retiredAt` string, date-time, required
    - `reason` string, required
    - `supersededBy` object[], required: The streaming detections that replace it
      - `slug` string, required
      - `name` string, required
      - `detectionId` string, uuid, nullable, required: The organization's streaming detection for this slug

## Other responses

- `400`: Bad request — input validation failed or the request was malformed
- `401`: Unauthorized — missing or invalid API key / session
- `403`: Forbidden — the authenticated user lacks the required permissions
- `404`: Library entry not found
- `422`: Entry already added or its tools are not connected
- `500`: Internal server error

---

[API](https://skmtc.dev/cotool/apis/cotool-api.md) - [All operations](https://skmtc.dev/cotool/apis/cotool-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cotool/apis/cotool-api/revisions/f5abe0add203?raw)