> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kyberis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Assess IOC

## Scope and credits

| Requirement     | Value                 |
| --------------- | --------------------- |
| Required scopes | `read:assessments`    |
| Credits         | 6 credits per request |

## IOC assessment behavior

`/v2/ioc-assessments` assesses the submitted IOC itself. It may enrich the assessment with intelligence about the exact IP, domain, URL, hash, or email subject, including targeted industries, targeted countries, and targeted campaigns when available. It does not expand event-correlated or co-occurring IOCs inline.

Use `/v2/relationships` with `relationship_types: ["ioc"]` when you need related indicators or event-correlation pivots for an IOC subject. Use `relationship_types: ["sector"]` or `relationship_types: ["country"]` when you need TIE-derived industry or geography pivots.


## OpenAPI

````yaml POST /v2/ioc-assessments
openapi: 3.1.0
info:
  description: Deterministic, evidence-backed threat assessment API for machine consumers.
  title: Threat Investigator API v2
  version: 0.1.0
servers: []
security: []
paths:
  /v2/ioc-assessments:
    post:
      tags:
        - Assessments
      summary: Structured IOC assessment (LLM-free)
      operationId: ioc_assessment_v2_ioc_assessments_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IocAssessmentRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssessmentResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - ApiKeyAuth: []
components:
  schemas:
    IocAssessmentRequest:
      additionalProperties: false
      properties:
        agent_context:
          anyOf:
            - $ref: '#/components/schemas/AgentContext'
            - type: 'null'
        context:
          anyOf:
            - $ref: '#/components/schemas/AssessmentContext'
            - type: 'null'
        expected_types:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Expected Types
        options:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Options
        query:
          anyOf:
            - maxLength: 1024
              type: string
            - type: 'null'
          title: Query
        resolution:
          anyOf:
            - $ref: '#/components/schemas/ResolutionOptions'
            - type: 'null'
        subject:
          anyOf:
            - $ref: '#/components/schemas/AssessmentSubject'
            - type: 'null'
        time_range:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Time Range
      title: IocAssessmentRequest
      type: object
    AssessmentResponse:
      properties:
        assessment_type:
          title: Assessment Type
          type: string
        caveats:
          items:
            type: string
          title: Caveats
          type: array
        confidence:
          title: Confidence
          type: number
        debug:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Debug
        evidence_refs:
          items:
            additionalProperties: true
            type: object
          title: Evidence Refs
          type: array
        input:
          additionalProperties: true
          title: Input
          type: object
        metadata:
          additionalProperties: true
          title: Metadata
          type: object
        priority:
          additionalProperties: true
          title: Priority
          type: object
        rationale_codes:
          items:
            type: string
          title: Rationale Codes
          type: array
        recommended_actions:
          items:
            type: string
          title: Recommended Actions
          type: array
        resolution:
          $ref: '#/components/schemas/ResolutionResult'
        signals:
          additionalProperties: true
          title: Signals
          type: object
        timestamp:
          title: Timestamp
          type: number
        trace_id:
          title: Trace Id
          type: string
      required:
        - assessment_type
        - trace_id
        - input
        - priority
        - confidence
        - rationale_codes
        - evidence_refs
        - recommended_actions
        - signals
        - caveats
        - metadata
        - timestamp
        - resolution
      title: AssessmentResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    AgentContext:
      additionalProperties: false
      properties:
        client:
          anyOf:
            - $ref: '#/components/schemas/AgentClientInfo'
            - type: 'null'
        constraints:
          anyOf:
            - $ref: '#/components/schemas/AgentConstraints'
            - type: 'null'
        objective:
          maxLength: 280
          minLength: 8
          title: Objective
          type: string
        parent_step_id:
          anyOf:
            - maxLength: 64
              type: string
            - type: 'null'
          title: Parent Step Id
        priority:
          anyOf:
            - enum:
                - low
                - normal
                - high
                - urgent
              type: string
            - type: 'null'
          title: Priority
        requested_outcome:
          maxLength: 280
          minLength: 3
          title: Requested Outcome
          type: string
        run_id:
          maxLength: 64
          minLength: 4
          title: Run Id
          type: string
        step_id:
          maxLength: 64
          minLength: 1
          title: Step Id
          type: string
        tags:
          anyOf:
            - items:
                type: string
              maxItems: 12
              type: array
            - type: 'null'
          title: Tags
        workflow_stage:
          enum:
            - resolve
            - evidence
            - relationships
            - assessment
            - hunt
            - hydrate
            - batch
            - finalize
            - other
          title: Workflow Stage
          type: string
      required:
        - objective
        - requested_outcome
        - workflow_stage
        - run_id
        - step_id
      title: AgentContext
      type: object
    AssessmentContext:
      additionalProperties: false
      properties:
        affected_cpes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Affected Cpes
        campaign_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Campaign Status
        evidence_refs:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/AssessmentEvidenceRef'
                  - type: string
              type: array
            - type: 'null'
          title: Evidence Refs
        intel_confidence:
          anyOf:
            - type: string
            - type: 'null'
          title: Intel Confidence
        known_exploited:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Known Exploited
        known_targets:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Known Targets
        targeted_industries:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Targeted Industries
        targeted_regions:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Targeted Regions
      title: AssessmentContext
      type: object
    ResolutionOptions:
      additionalProperties: false
      properties:
        include_aliases:
          default: false
          title: Include Aliases
          type: boolean
        include_metadata:
          default: false
          title: Include Metadata
          type: boolean
        max_results:
          default: 5
          maximum: 25
          minimum: 1
          title: Max Results
          type: integer
      title: ResolutionOptions
      type: object
    AssessmentSubject:
      additionalProperties: false
      properties:
        canonical_id:
          title: Canonical Id
          type: string
        canonical_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Canonical Name
        entity_type:
          title: Entity Type
          type: string
      required:
        - entity_type
        - canonical_id
      title: AssessmentSubject
      type: object
    ResolutionResult:
      properties:
        candidates:
          items:
            $ref: '#/components/schemas/EntityResolutionCandidate'
          title: Candidates
          type: array
        canonical_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Canonical Id
        canonical_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Canonical Name
        entity_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Entity Type
        input_mode:
          anyOf:
            - enum:
                - subject
                - query
              type: string
            - type: 'null'
          title: Input Mode
        resolution_confidence:
          anyOf:
            - type: number
            - type: 'null'
          title: Resolution Confidence
        status:
          enum:
            - resolved
            - ambiguous
            - not_found
            - not_applicable
          title: Status
          type: string
      required:
        - status
      title: ResolutionResult
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    AgentClientInfo:
      additionalProperties: false
      properties:
        agent_name:
          anyOf:
            - maxLength: 64
              type: string
            - type: 'null'
          title: Agent Name
        agent_version:
          anyOf:
            - maxLength: 32
              type: string
            - type: 'null'
          title: Agent Version
        framework:
          anyOf:
            - maxLength: 32
              type: string
            - type: 'null'
          title: Framework
      title: AgentClientInfo
      type: object
    AgentConstraints:
      additionalProperties: false
      properties:
        latency_budget_ms:
          anyOf:
            - maximum: 30000
              minimum: 50
              type: integer
            - type: 'null'
          title: Latency Budget Ms
        max_results_budget:
          anyOf:
            - maximum: 200
              minimum: 1
              type: integer
            - type: 'null'
          title: Max Results Budget
        min_resolution_confidence:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          title: Min Resolution Confidence
        strict_mode:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Strict Mode
      title: AgentConstraints
      type: object
    AssessmentEvidenceRef:
      additionalProperties: false
      properties:
        id:
          title: Id
          type: string
        type:
          title: Type
          type: string
      required:
        - type
        - id
      title: AssessmentEvidenceRef
      type: object
    EntityResolutionCandidate:
      properties:
        aliases:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Aliases
        canonical_id:
          title: Canonical Id
          type: string
        canonical_name:
          title: Canonical Name
          type: string
        entity_type:
          title: Entity Type
          type: string
        match_type:
          title: Match Type
          type: string
        matched_on:
          anyOf:
            - type: string
            - type: 'null'
          title: Matched On
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
        score:
          title: Score
          type: number
      required:
        - entity_type
        - canonical_id
        - canonical_name
        - match_type
        - score
      title: EntityResolutionCandidate
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: ApiKey <key_id>:<secret>
      in: header
      name: Authorization
      type: apiKey

````