> ## 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. # Add a detection library entry > Creates an org-owned detection from the entry, publishes its notebook as version 1, and enables the entry's default schedule. ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json post /api/detection-library/{slug}/add 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-library/{slug}/add: post: tags: - Detections summary: Add a detection library entry description: >- Creates an org-owned detection from the entry, publishes its notebook as version 1, and enables the entry's default schedule. parameters: - in: path name: slug schema: type: string pattern: ^[a-z0-9]+(-[a-z0-9]+)*$ required: true responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string format: uuid chatId: type: - string - 'null' format: uuid description: >- Caller-owned editor chat on detail responses; always null in catalog rows revision: type: string pattern: ^[0-9a-f]{64}$ name: type: - string - 'null' summary: type: - string - 'null' description: >- 1–3 sentence plain-prose headline of what the detection is meant to detect. No bullet lists. description: type: - string - 'null' description: >- Operational GitHub-flavored markdown: typically two or three bullets covering the signal and the fire condition toolNames: type: array items: type: string mitreTechniqueIds: type: array items: type: string metadataStatus: type: string enum: - pending - ready - failed librarySlug: type: - string - 'null' description: >- Detection library entry this detection was added from, when any createdAt: type: string format: date-time updatedAt: type: string format: date-time publishedVersionId: type: - string - 'null' format: uuid recentHits: type: array items: type: object properties: id: type: string format: uuid executionId: type: string format: uuid entity: type: string entityType: type: - string - 'null' severity: type: - string - 'null' enum: - low - medium - high - critical - null headline: type: - string - 'null' summary: type: - string - 'null' evidence: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: 'null' description: The emitted row backing this hit closedAt: type: - string - 'null' format: date-time lastSeenAt: type: string format: date-time lastSeenExecutionId: type: - string - 'null' format: uuid seenCount: type: integer exclusiveMinimum: 0 linkedAlert: type: - object - 'null' properties: id: type: string format: uuid displayId: type: string pattern: ^COT-\d+$ status: type: string enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - dismissed - duplicate - expired description: >- 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: type: - string - 'null' enum: - true_positive - false_positive - true_positive_benign - null description: >- Derived disposition for closed alerts. This is not stored separately from status. assignedAgent: type: - object - 'null' properties: id: type: string format: uuid name: type: string minLength: 1 required: - id - name additionalProperties: false required: - id - displayId - status - derivedDisposition - assignedAgent additionalProperties: false createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - executionId - entity - entityType - severity - headline - summary - evidence - closedAt - lastSeenAt - lastSeenExecutionId - seenCount - linkedAlert - createdAt - updatedAt additionalProperties: false feedback: type: object properties: detectionId: type: string format: uuid windowDays: type: integer exclusiveMinimum: 0 dispositions: type: object properties: truePositive: type: integer minimum: 0 falsePositive: type: integer minimum: 0 benign: type: integer minimum: 0 required: - truePositive - falsePositive - benign additionalProperties: false statuses: type: object properties: open: type: integer minimum: 0 inProgress: type: integer minimum: 0 escalated: type: integer minimum: 0 duplicate: type: integer minimum: 0 dismissed: type: integer minimum: 0 expired: type: integer minimum: 0 required: - open - inProgress - escalated - duplicate - dismissed - expired additionalProperties: false precision: type: object properties: value: type: - number - 'null' minimum: 0 maximum: 1 numerator: type: integer minimum: 0 denominator: type: integer minimum: 0 required: - value - numerator - denominator additionalProperties: false versions: type: array items: type: object properties: versionId: type: string format: uuid version: type: integer exclusiveMinimum: 0 dispositions: type: object properties: truePositive: type: integer minimum: 0 falsePositive: type: integer minimum: 0 benign: type: integer minimum: 0 required: - truePositive - falsePositive - benign additionalProperties: false precision: type: object properties: value: type: - number - 'null' minimum: 0 maximum: 1 numerator: type: integer minimum: 0 denominator: type: integer minimum: 0 required: - value - numerator - denominator additionalProperties: false required: - versionId - version - dispositions - precision additionalProperties: false falsePositiveEntities: type: array items: type: object properties: entity: type: string entityType: type: - string - 'null' count: type: integer exclusiveMinimum: 0 required: - entity - entityType - count additionalProperties: false actorSplit: type: object properties: human: type: object properties: truePositive: type: integer minimum: 0 falsePositive: type: integer minimum: 0 benign: type: integer minimum: 0 required: - truePositive - falsePositive - benign additionalProperties: false agent: type: object properties: truePositive: type: integer minimum: 0 falsePositive: type: integer minimum: 0 benign: type: integer minimum: 0 required: - truePositive - falsePositive - benign additionalProperties: false required: - human - agent additionalProperties: false scheduledExecutions: type: object properties: total: type: integer minimum: 0 succeeded: type: integer minimum: 0 failed: type: integer minimum: 0 interrupted: type: integer minimum: 0 running: type: integer minimum: 0 successRate: type: - number - 'null' minimum: 0 maximum: 1 averageRuntimeMs: type: - number - 'null' minimum: 0 errorCount: type: integer minimum: 0 recentErrors: type: array items: type: object properties: message: type: string count: type: integer exclusiveMinimum: 0 lastOccurredAt: type: string format: date-time required: - message - count - lastOccurredAt additionalProperties: false lastScheduledRunAt: type: - string - 'null' format: date-time lastFinishedStatus: type: - string - 'null' enum: - succeeded - failed - interrupted - null required: - total - succeeded - failed - interrupted - running - successRate - averageRuntimeMs - errorCount - recentErrors - lastScheduledRunAt - lastFinishedStatus additionalProperties: false volume: type: object properties: hits: type: integer minimum: 0 alerts: type: integer minimum: 0 lastResultAt: type: - string - 'null' format: date-time lastAlertAt: type: - string - 'null' format: date-time required: - hits - alerts - lastResultAt - lastAlertAt additionalProperties: false everEscalated: type: integer minimum: 0 meanTimeToDispositionSeconds: type: - number - 'null' minimum: 0 required: - detectionId - windowDays - dispositions - statuses - precision - versions - falsePositiveEntities - actorSplit - scheduledExecutions - volume - everEscalated - meanTimeToDispositionSeconds additionalProperties: false required: - id - chatId - revision - name - summary - description - toolNames - mitreTechniqueIds - metadataStatus - librarySlug - createdAt - updatedAt - publishedVersionId - recentHits - feedback additionalProperties: false '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' '404': description: Library entry not found content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Entry already added or its tools are not connected content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: shell label: cURL source: >- curl -X POST "https://app.cotool.ai/api/detection-library/:slug/add" \ -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` ````