openapi: 3.1.0
info:
  title: Cortex API
  version: 0.0.1
  summary: 面向数据解析、存储、知识构建、效果评测与数据合成的厂商中立 API。/ Vendor-neutral APIs for parse,
    storage, knowledge, evaluation, and synthesis.
  description: Cortex 通过统一契约暴露五类核心
    API：Parse、Storage、Knowledge、Evaluation、Synthesis。各域共享厂商中立的数据模型、统一的 Job
    体系、统一权限边界，以及基于 OpenTelemetry 的可观测能力。
servers:
  - url: https://api.cortex.com
    description: Production / 生产环境
  - url: " https://dev.cortex.com"
    description: Development / 测试环境
tags:
  - name: Health
    description: 运行存活与依赖就绪探针。/ Runtime liveness and dependency readiness probes.
  - name: Observability
    description: 对齐 OpenTelemetry 的遥测与指标接口。/ OpenTelemetry-aligned telemetry and
      metrics endpoints.
  - name: Jobs
    description: 通用长任务查询与控制。/ Generic long-running job inspection and control.
  - name: Parse
    description: 面向 URL 与文件的引擎无关解析、标准化与持久化。/ Engine-agnostic parsing, normalization,
      and persistence for URLs and files.
  - name: Storage
    description: 上传、查询和下载 S3 后端对象。 / Upload, inspect, and download S3-backed objects.
  - name: Knowledge
    description: Dataset lifecycle plus Cognee-backed Add, Cognify, Memify, and
      Search operations. / 数据集生命周期与基于 Cognee 的 Add、Cognify、Memify、Search 操作。
  - name: Evaluation
    description: AI 评测引擎、指标目录、同步校验与异步评测作业。/ AI evaluation engines, metric catalogs,
      synchronous checks, and asynchronous evaluation jobs.
  - name: Synthesis
    description: 数据合成引擎以及同步、异步生成工作流。/ Synthetic data engines plus synchronous and
      asynchronous generation workflows.
  - name: Dev Auth
    description: 仅本地开发环境启用的 token 生成辅助接口。/ Local-development-only token issuance helper.
paths:
  /v1/health/live:
    get:
      tags:
        - Health
      summary: Liveness probe
      operationId: getLiveness
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /v1/health/ready:
    get:
      tags:
        - Health
      summary: Readiness probe
      operationId: getReadiness
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
        "503":
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
      security:
        - BearerAuth: []
  /v1/jobs/{jobId}:
    get:
      tags:
        - Jobs
      summary: Get job status
      description: Return the current state, timestamps, and telemetry context for one
        long-running job.
      operationId: getJob
      security:
        - BearerAuth: []
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
            description: Job identifier returned by a create-job endpoint such as Parse,
              Add, Cognify, or Memify.
            examples:
              - job_71fe50adf1cb4981bb322f0d74f32598
            title: Jobid
          description: Job identifier returned by a create-job endpoint such as Parse,
            Add, Cognify, or Memify.
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatusDetail"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/jobs/{jobId}/events:
    get:
      tags:
        - Jobs
      summary: List job events
      description: Return the ordered event stream for one job, newest first according
        to the service implementation.
      operationId: listJobEvents
      security:
        - BearerAuth: []
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
            description: Job identifier whose event stream should be returned.
            examples:
              - job_71fe50adf1cb4981bb322f0d74f32598
            title: Jobid
          description: Job identifier whose event stream should be returned.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            description: "Maximum number of events to return. Best default: 100."
            examples:
              - 100
            default: 100
            title: Limit
          description: "Maximum number of events to return. Best default: 100."
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/JobEvent"
                title: Response Listjobevents
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/jobs/{jobId}/cancel:
    post:
      tags:
        - Jobs
      summary: Cancel a queued or running job
      description: Request cancellation of a queued or running job and return the
        updated status snapshot.
      operationId: cancelJob
      security:
        - BearerAuth: []
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
            description: Job identifier to cancel.
            examples:
              - job_71fe50adf1cb4981bb322f0d74f32598
            title: Jobid
          description: Job identifier to cancel.
      responses:
        "202":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatusDetail"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/eval/engines:
    get:
      tags:
        - Evaluation
      summary: List evaluation engines
      description: Returns the currently registered evaluation engines, supported
        evaluation types, execution modes, and default profile hints.
      operationId: listEvalEngines
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvalEngineList"
      security:
        - BearerAuth: []
  /v1/eval/metrics:
    get:
      tags:
        - Evaluation
      summary: List normalized evaluation metrics
      description: Returns the normalized Cortex metric catalog that maps
        business-facing metric keys to engine-native implementations across
        DeepEval, EvalScope, and future adapters.
      operationId: listEvalMetrics
      security:
        - BearerAuth: []
      parameters:
        - name: evalType
          in: query
          required: false
          schema:
            anyOf:
              - $ref: "#/components/schemas/EvalType"
              - type: "null"
            title: Evaltype
        - name: engineId
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: Engineid
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvalMetricCatalog"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/eval/sync:
    post:
      tags:
        - Evaluation
      summary: Execute a synchronous evaluation run
      description: Runs a small evaluation workload synchronously. Recommended for
        smoke checks, profile tuning, and low-cardinality datasets; larger
        workloads should use `/v1/eval/jobs`.
      operationId: runEvaluationSync
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EvalSyncRequest"
              description: "Unified evaluation request body. Required: `eval_type` and
                `input`. `engine_id` defaults to `auto`."
            examples:
              rag_eval:
                summary: RAG evaluation / RAG 评测
                description: Recommended synchronous evaluation for a small RAG validation
                  dataset.
                value:
                  name: Fintech-RAG-QA-Eval
                  eval_type: rag
                  engine_id: auto
                  input:
                    type: dataset
                    dataset_id: ds_001
                    field_mapping:
                      user_input: question
                      actual_output: answer
                      retrieval_contexts: contexts
                  target:
                    type: api
                    endpoint_url: https://ordix.internal/v1/query
                    timeout_seconds: 30
                  metrics:
                    - metric_key: rag.faithfulness
                      threshold: 0.8
                    - metric_key: rag.answer_relevance
                      threshold: 0.7
              deepeval_multi_turn_sync:
                summary: DeepEval multi-turn sync / DeepEval 多轮同步评测
                description: Inline multi-turn conversation evaluation for quick regression
                  checks.
                value:
                  name: swagger-dialog-smoke
                  eval_type: multi_turn
                  engine_id: deepeval
                  input:
                    type: inline_test_cases
                    test_cases:
                      - conversation_turns:
                          - role: user
                            content: Help me parse a PDF from storage.
                          - role: assistant
                            content: Upload it to Storage and submit a Parse job.
                        metadata:
                          case_id: dialog-smoke-001
                  metrics:
                    - metric_key: dialog.conversation_relevancy
                      threshold: 0.75
                    - metric_key: dialog.conversation_completeness
                      threshold: 0.75
              evalscope_perf_sync:
                summary: EvalScope perf sync / EvalScope 性能同步评测
                description: Small performance smoke request routed to EvalScope. In local
                  Docker, the target can point at the Cortex readiness endpoint.
                value:
                  name: swagger-perf-smoke
                  eval_type: perf
                  engine_id: evalscope
                  input:
                    type: builtin_dataset
                    builtin_dataset_key: openqa
                  target:
                    type: api
                    endpoint_url: http://127.0.0.1:8080/v1/health/ready
                    timeout_seconds: 30
                  metrics:
                    - metric_key: perf.qps
                      threshold: 1
                    - metric_key: perf.p90_latency
                      threshold: 2
                  engine_options:
                    parallel:
                      - 1
                    number:
                      - 5
                    stream: false
        required: true
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvalRunResult"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
      security:
        - BearerAuth: []
  /v1/eval/jobs:
    post:
      tags:
        - Evaluation
      summary: Submit an asynchronous evaluation job
      description: Queues a longer-running evaluation workload and returns a Cortex
        job handle for polling, events, and result retrieval.
      operationId: createEvalJob
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: Optional idempotency key for asynchronous evaluation job
              submission.
            examples:
              - parse-demo-001
            title: Idempotency-Key
          description: Optional idempotency key for asynchronous evaluation job submission.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EvalJobSubmitRequest"
              description: Async evaluation job request. Use this for larger datasets, agent
                regressions, or scheduled validation workloads.
            examples:
              agent_eval_job:
                summary: Agent evaluation job / Agent 评测作业
                description: Recommended async submission for larger agentic or regression
                  workloads.
                value:
                  name: Support-Agent-Regressions
                  eval_type: agentic
                  engine_id: auto
                  input:
                    type: dataset
                    dataset_id: ds_agent_suite
                  metrics:
                    - metric_key: agent.task_completion
                      threshold: 0.8
                    - metric_key: agent.tool_correctness
                      threshold: 0.8
                  webhook:
                    url: https://example.com/hooks/cortex/eval
                    event_types:
                      - job.succeeded
                      - job.failed
              evalscope_perf_job:
                summary: EvalScope perf async job / EvalScope 异步性能评测
                description: Recommended async submission for larger performance workloads.
                value:
                  name: swagger-perf-job
                  eval_type: perf
                  engine_id: evalscope
                  input:
                    type: builtin_dataset
                    builtin_dataset_key: openqa
                  target:
                    type: api
                    protocol: openai_compatible
                    endpoint_url: http://127.0.0.1:8080/v1/health/ready
                    timeout_seconds: 60
                  metrics:
                    - metric_key: perf.qps
                      threshold: 1
                    - metric_key: perf.p99_latency
                      threshold: 5
                    - metric_key: perf.output_tokens_per_second
                      threshold: 1
                  engine_options:
                    parallel:
                      - 1
                      - 2
                    number:
                      - 10
                    stream: false
              deepeval_custom_job:
                summary: DeepEval custom async job / DeepEval 异步自定义评测
                description: Custom GEval-style quality check with a caller-provided criterion.
                value:
                  name: swagger-custom-quality-job
                  eval_type: custom
                  engine_id: deepeval
                  input:
                    type: inline_test_cases
                    test_cases:
                      - user_input: Explain Cortex Parse in one sentence.
                        actual_output: Cortex Parse converts web pages and files into Markdown with
                          normalized metadata.
                        expected_output: Cortex Parse should mention Markdown and standardized metadata.
                  metrics:
                    - metric_key: quality.correctness
                      threshold: 0.8
                      params:
                        criteria: Score whether the answer correctly explains the business purpose of
                          Cortex Parse.
                  webhook:
                    url: https://example.com/hooks/cortex/eval
                    event_types:
                      - job.succeeded
                      - job.failed
      responses:
        "202":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvalJobAccepted"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/eval/jobs/{jobId}/result:
    get:
      tags:
        - Evaluation
      summary: Get a completed evaluation result
      description: Returns the completed evaluation result when the async job
        succeeds, or a 409 job status payload while work is still in progress.
      operationId: getEvalResult
      security:
        - BearerAuth: []
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
            title: Jobid
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/EvalRunResult"
                  - $ref: "#/components/schemas/JobStatusDetail"
                title: Response Getevalresult
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatusDetail"
          description: Conflict
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/knowledge/datasets:
    post:
      tags:
        - Knowledge
      summary: Create a knowledge dataset
      description: Create a dataset that Add, Cognify, Memify, and Search operations
        will target.
      operationId: createKnowledgeDataset
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KnowledgeDatasetCreateRequest"
              description: Dataset creation request. `dataset_key` and `display_name` are
                required; other fields are optional with documented defaults.
            examples:
              swagger_demo_dataset:
                summary: Swagger demo dataset / Swagger 演示数据集
                description: Creates a tenant-shared dataset used by the one-click Knowledge
                  examples below. If this key already exists, change the suffix
                  and reuse the same key in Add, Cognify, Memify, and Search
                  requests.
                value:
                  dataset_key: swagger_knowledge_demo
                  display_name: Swagger Knowledge Demo
                  description: Small Knowledge dataset for Swagger Try it out tests using inline
                    text, public URIs, and uploaded storage objects.
                  tags:
                    - swagger
                    - knowledge
                    - demo
                  retention_class: temporary
                  metadata:
                    domain: cortex
                    owner_team: platform
                    demo_flow: storage-parse-knowledge
                  access_policy:
                    access_level: tenant_shared
                    classification_labels:
                      - internal
                    allowed_role_keys:
                      - tenant_admin
                      - analyst
                    denied_role_keys: []
                    purpose_tags:
                      - search
                      - assistant
                      - swagger_demo
                    constraints: {}
              product_docs_dataset:
                summary: Product docs dataset / 产品文档数据集
                description: Creates a tenant-shared dataset suitable for Parse -> Add -> Search
                  workflows.
                value:
                  dataset_key: product_docs
                  display_name: Product Docs
                  description: Primary product knowledge base for demos and regression tests.
                  tags:
                    - docs
                    - product
                  retention_class: standard
                  metadata:
                    domain: product
                    owner_team: platform
                  access_policy:
                    access_level: tenant_shared
                    classification_labels:
                      - internal
                    allowed_role_keys:
                      - tenant_admin
                      - analyst
                    denied_role_keys: []
                    purpose_tags:
                      - search
                      - assistant
                    constraints: {}
        required: true
      responses:
        "201":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KnowledgeDataset"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
      security:
        - BearerAuth: []
  /v1/knowledge/datasets/{datasetId}:
    get:
      tags:
        - Knowledge
      summary: Get dataset metadata and counters
      description: Return one dataset including audit info, counters, and access policy.
      operationId: getKnowledgeDataset
      security:
        - BearerAuth: []
      parameters:
        - name: datasetId
          in: path
          required: true
          schema:
            type: string
            description: Knowledge dataset identifier returned by `/v1/knowledge/datasets`.
            examples:
              - dset_9558cfc9178444e4a4c60d5658db78f5
            title: Datasetid
          description: Knowledge dataset identifier returned by `/v1/knowledge/datasets`.
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KnowledgeDataset"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/knowledge/add/jobs:
    post:
      tags:
        - Knowledge
      summary: Submit a Cognee Add job
      description: Queue an Add job to ingest objects, documents, text, or URIs into a
        knowledge dataset.
      operationId: createAddJob
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: "Optional idempotency key for safely retrying Add job submission.
              Best default: omit."
            examples:
              - parse-demo-001
            title: Idempotency-Key
          description: "Optional idempotency key for safely retrying Add job submission.
            Best default: omit."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddJobRequest"
              description: Add job request. Provide either `dataset_id` or `dataset_key`, then
                list one or more `inputs`.
            examples:
              swagger_inline_text_ingest:
                summary: Runnable inline text Add / 可直接运行的内联文本 Add
                description: Use after creating `swagger_knowledge_demo`. This is the safest
                  local Swagger smoke example because it does not require an
                  existing Storage object or external network access.
                value:
                  dataset_key: swagger_knowledge_demo
                  inputs:
                    - input_type: text
                      text: >-
                        # Cortex API Demo Knowledge


                        Cortex provides Parse, Storage, Knowledge, Evaluation,
                        and Synthesis APIs. Parse normalizes URLs and files into
                        Markdown. Storage keeps source files in S3-compatible
                        buckets. Knowledge uses Add, Cognify, Memify, and Search
                        to build graph-aware retrieval workflows.
                      label: Cortex API demo note
                      node_set:
                        - swagger_demo
                        - docs
                      metadata:
                        source: swagger-inline
                        domain: cortex
                        document_type: demo_note
                  options:
                    normalize_text: true
                    structured_ingest: true
                    incremental: true
                    persist_source_copy: false
              public_uri_ingest:
                summary: Public URI Add / 公共 URI Add
                description: Use when the Knowledge runtime can fetch public URLs. This keeps
                  the request copy-pasteable while exercising the URI input
                  path.
                value:
                  dataset_key: swagger_knowledge_demo
                  inputs:
                    - input_type: uri
                      uri: https://raw.githubusercontent.com/crabcanon/cortex/main/README.md
                      label: Cortex README from GitHub
                      node_set:
                        - swagger_demo
                        - docs
                        - uri
                      metadata:
                        source: github-raw
                        domain: cortex
                        document_type: readme
                  options:
                    normalize_text: true
                    structured_ingest: true
                    incremental: true
                    persist_source_copy: true
              storage_object_ingest:
                summary: Storage object Add / 存储对象 Add
                description: Use after uploading a file with `POST /v1/storage/files`; replace
                  `object_id` with the returned object id. This documents the
                  Storage -> Knowledge path.
                value:
                  dataset_key: swagger_knowledge_demo
                  inputs:
                    - input_type: object_id
                      object_id: obj_a3da967e3ca446cab3631bb7
                      label: Uploaded README or PDF
                      node_set:
                        - swagger_demo
                        - storage
                      metadata:
                        source: storage
                        bucket: cortex-local
                        object_key: tenant_demo/obj_a3da967e3ca446cab3631bb7/README.md
                  options:
                    normalize_text: true
                    structured_ingest: true
                    incremental: true
                    persist_source_copy: true
              parsed_document_ingest:
                summary: Parsed document Add / 解析文档 Add
                description: Recommended Add request after a file has been uploaded and
                  optionally parsed.
                value:
                  dataset_key: product_docs
                  inputs:
                    - input_type: object_id
                      object_id: obj_3f6c1d5e9b1646b5a4eabdbf8b417bd3
                      label: Uploaded source file
                      node_set:
                        - docs
                      metadata:
                        source: storage
                    - input_type: document_id
                      document_id: doc_71fe50adf1cb4981bb322f0d74f32598
                      label: Normalized parsed document
                      node_set:
                        - docs
                        - parsed
                      metadata:
                        source: parse
                  options:
                    normalize_text: true
                    structured_ingest: true
                    incremental: true
                    persist_source_copy: true
                  webhook:
                    url: https://example.com/hooks/cortex/knowledge-add
                    event_types:
                      - job.succeeded
                      - job.failed
                    headers:
                      X-Consumer: knowledge-worker
              direct_text_ingest:
                summary: Direct text ingest / 直接文本摄入
                description: Useful for small snippets, notes, or quick operator tests without a
                  prior upload.
                value:
                  dataset_key: product_docs
                  inputs:
                    - input_type: text
                      text: |-
                        # Cortex Notes

                        Cortex supports Parse, Storage, and Knowledge APIs.
                      label: Quick note
                      node_set:
                        - notes
                      metadata:
                        source: manual
                  options:
                    normalize_text: true
                    structured_ingest: true
                    incremental: true
                    persist_source_copy: false
      responses:
        "202":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobAccepted"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/knowledge/cognify/jobs:
    post:
      tags:
        - Knowledge
      summary: Submit a Cognify job
      description: Queue a Cognify job to derive graph structure from dataset content.
      operationId: createCognifyJob
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: "Optional idempotency key for safely retrying Cognify job
              submission. Best default: omit."
            examples:
              - parse-demo-001
            title: Idempotency-Key
          description: "Optional idempotency key for safely retrying Cognify job
            submission. Best default: omit."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CognifyJobRequest"
              description: Cognify job request. Provide either `dataset_id` or `dataset_key`;
                all other fields are optional.
            examples:
              swagger_demo_cognify:
                summary: Runnable Cognify for demo dataset / 演示数据集 Cognify
                description: Run after the `swagger_inline_text_ingest` Add job succeeds. It
                  builds graph structure for the demo dataset with a small
                  chunking budget.
                value:
                  dataset_key: swagger_knowledge_demo
                  incremental_loading: true
                  graph_prompt_profile: simple
                  chunking:
                    enabled: true
                    strategy: semantic
                    target_tokens: 384
                    overlap_tokens: 48
                    max_chunks: 64
              recommended_cognify:
                summary: Recommended Cognify request / 推荐 Cognify 请求
                description: Builds or refreshes the dataset graph with the default prompt
                  profile and semantic chunking.
                value:
                  dataset_key: product_docs
                  incremental_loading: true
                  graph_prompt_profile: default
                  chunking:
                    enabled: true
                    strategy: semantic
                    target_tokens: 512
                    overlap_tokens: 64
                    max_chunks: 256
                  webhook:
                    url: https://example.com/hooks/cortex/cognify
                    event_types:
                      - job.succeeded
                      - job.failed
                    headers:
                      X-Consumer: graph-sync
      responses:
        "202":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobAccepted"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/knowledge/memify/jobs:
    post:
      tags:
        - Knowledge
      summary: Submit a Memify job
      description: Queue a Memify enrichment job over an existing dataset graph.
      operationId: createMemifyJob
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: "Optional idempotency key for safely retrying Memify job
              submission. Best default: omit."
            examples:
              - parse-demo-001
            title: Idempotency-Key
          description: "Optional idempotency key for safely retrying Memify job
            submission. Best default: omit."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MemifyJobRequest"
              description: Memify job request. Provide either `dataset_id` or `dataset_key`;
                `pipeline` defaults to `coding_rules`.
            examples:
              swagger_triplet_memify:
                summary: Runnable triplet Memify / 可运行的三元组 Memify
                description: Run after Cognify. The Python Cognee adapter currently supports
                  `triplet_embeddings` and `session_persistence` for live
                  execution.
                value:
                  dataset_key: swagger_knowledge_demo
                  pipeline: triplet_embeddings
                  node_type: document
                  node_names: []
                  session_ids: []
              recommended_memify:
                summary: Recommended Memify request / 推荐 Memify 请求
                description: Runs the default coding-rules enrichment pipeline over the selected
                  dataset.
                value:
                  dataset_key: product_docs
                  pipeline: coding_rules
                  node_type: document
                  node_names:
                    - Cortex API Overview
                    - Runtime Configuration Guide
                  session_ids: []
                  webhook:
                    url: https://example.com/hooks/cortex/memify
                    event_types:
                      - job.succeeded
                      - job.failed
                    headers:
                      X-Consumer: knowledge-memify
      responses:
        "202":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobAccepted"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/knowledge/search:
    post:
      tags:
        - Knowledge
      summary: Search across datasets and knowledge graphs
      description: Search across one or more datasets using semantic, graph, or hybrid
        retrieval. Use `recommended_graph_completion` for the most balanced
        default behavior.
      operationId: searchKnowledge
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequest"
              description: Knowledge search request. `query_text` is required; dataset scope
                and filters are optional.
            examples:
              swagger_demo_search:
                summary: Runnable demo search / 可运行的演示搜索
                description: Run after Add and preferably after Cognify. Uses the demo dataset
                  key from the Swagger dataset example.
                value:
                  query_text: What Cortex APIs are available and what does Knowledge do?
                  dataset_keys:
                    - swagger_knowledge_demo
                  search_type: GRAPH_COMPLETION
                  top_k: 5
                  filters:
                    document_ids: []
                    object_ids: []
                    tags: []
                    node_sets:
                      - swagger_demo
                    metadata: {}
                  only_context: false
                  include_provenance: true
                  include_graph_paths: true
                  timeout_seconds: 30
              storage_object_search:
                summary: Search storage-backed knowledge / 搜索存储来源知识
                description: Use after adding an uploaded Storage object. Replace the object id
                  with the id returned by `/v1/storage/files` when you want to
                  narrow results.
                value:
                  query_text: Summarize the uploaded README or PDF.
                  dataset_keys:
                    - swagger_knowledge_demo
                  search_type: CHUNKS
                  top_k: 5
                  filters:
                    document_ids: []
                    object_ids:
                      - obj_a3da967e3ca446cab3631bb7
                    tags: []
                    node_sets:
                      - storage
                    metadata: {}
                  only_context: true
                  include_provenance: true
                  include_graph_paths: false
                  timeout_seconds: 15
              recommended_graph_completion:
                summary: Recommended graph completion search / 推荐图谱补全搜索
                description: A good default search request for answering a question with
                  graph-aware context.
                value:
                  query_text: What does the documentation say about Cortex parse workflows?
                  dataset_keys:
                    - product_docs
                  search_type: GRAPH_COMPLETION
                  top_k: 10
                  filters:
                    document_ids: []
                    object_ids: []
                    tags:
                      - docs
                    node_sets:
                      - docs
                    metadata:
                      domain: product
                  only_context: false
                  include_provenance: true
                  include_graph_paths: true
                  timeout_seconds: 30
              chunk_search:
                summary: Chunk-level retrieval / Chunk 级检索
                description: Useful when you only want ranked context snippets without a
                  synthesized answer.
                value:
                  query_text: OpenTelemetry integration
                  dataset_keys:
                    - product_docs
                  search_type: CHUNKS
                  top_k: 5
                  only_context: true
                  include_provenance: true
                  include_graph_paths: false
                  timeout_seconds: 15
        required: true
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
      security:
        - BearerAuth: []
  /metrics:
    get:
      tags:
        - Observability
      summary: Prometheus scrape endpoint
      operationId: getMetrics
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/parse/engines:
    get:
      tags:
        - Parse
      summary: List available parse engines
      description: Return the registered parser engines, supported source kinds,
        default scene, supported scenes, and the default internal profile that
        the Parse request compiler will bind for each engine.
      operationId: listParseEngines
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParseEngineList"
      security:
        - BearerAuth: []
  /v1/parse/profiles:
    get:
      tags:
        - Parse
      summary: List parser profiles
      description: Return the internal parser profiles available to operators and
        debugging workflows. Most API callers should not need them because the
        public Parse API compiles `source + engine_id (+ scene)` into these
        profiles automatically.
      operationId: listParserProfiles
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParserProfileList"
      security:
        - BearerAuth: []
  /v1/parse/sync:
    post:
      tags:
        - Parse
      summary: Parse content synchronously
      description: Synchronously parse one or more source locators into LLM-ready
        Markdown. The public contract is centered on `sources`, `engine_id`, and
        optional `scene`.
      operationId: parseContentSync
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ParseSubmitRequest"
              description: "Unified Parse request body. Required: `sources`. `engine_id`
                defaults to `auto`, and `scene` is optional."
            examples:
              auto_web_batch_parse:
                summary: Auto-routed web batch parse / 自动路由网页批量解析
                description: Submit one or more source locators and let Cortex pick the best
                  active engine and scene automatically.
                value:
                  sources:
                    - https://docs.cognee.ai/core-concepts/overview
                    - https://docs.crawl4ai.com/advanced/advanced-features/
                  engine_id: auto
              crawl4ai_deep_web:
                summary: Crawl4AI deep-web parse / Crawl4AI 深度网页解析
                description: Use Crawl4AI explicitly with the high-intensity `deep_web` scene.
                  This keeps fallback disabled and always routes the request to
                  Crawl4AI.
                value:
                  sources:
                    - https://docs.crawl4ai.com/advanced/advanced-features/
                  engine_id: crawl4ai
                  scene: deep_web
              minio_object_auto:
                summary: MinIO/S3 object parse / MinIO/S3 对象解析
                description: Parse a Cortex-managed object stored in MinIO/S3. The locator may
                  be the storage object key, an `s3://bucket/key` URI, or
                  `cortex://objects/{object_id}`; Cortex extracts the `obj_...`
                  id, signs a download URL, and detects MIME type.
                value:
                  sources:
                    - s3://cortex-local/tenant_demo/obj_a3da967e3ca446cab3631bb7/bofa_note.pdf
                  engine_id: auto
                  scene: document_ai
        required: true
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParseBatchResult"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
      security:
        - BearerAuth: []
  /v1/parse/jobs:
    post:
      tags:
        - Parse
      summary: Submit an asynchronous parse job
      description: Queue one async parse job per source using the same unified public
        Parse contract. Add optional `priority` and `webhook` only when job
        control is needed.
      operationId: createParseJob
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: "Optional idempotency key for safely retrying asynchronous job
              submission. Best default: omit unless a client may re-send the
              same create request."
            examples:
              - parse-demo-001
            title: Idempotency-Key
          description: "Optional idempotency key for safely retrying asynchronous job
            submission. Best default: omit unless a client may re-send the same
            create request."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ParseJobSubmitRequest"
              description: Unified async Parse request. `sources` may contain one or more
                locators; `engine_id` defaults to `auto`.
            examples:
              async_auto_batch_parse:
                summary: Async auto-routed batch parse / 异步自动路由批量解析
                description: Recommended when you want one async parse job per source with the
                  same high-level routing contract.
                value:
                  sources:
                    - https://docs.cognee.ai/core-concepts/overview
                    - s3://demo-bucket/manuals/architecture.pdf
                  engine_id: auto
                  priority: 5
                  webhook:
                    url: https://example.com/hooks/cortex/parse
                    secret_ref: vault:cortex/webhooks/parse
                    event_types:
                      - job.succeeded
                      - job.failed
                    headers:
                      X-Consumer: knowledge-pipeline
              async_docling_minio_pdf:
                summary: Docling async MinIO PDF parse / Docling 异步解析 MinIO PDF
                description: Use this for PDFs uploaded through Cortex Storage. Start the
                  `cortex-parse-worker-docling` worker/profile so the job is
                  claimed by the Docling runtime worker instead of the slim
                  parse worker.
                value:
                  sources:
                    - s3://cortex-local/tenant_demo/obj_a3da967e3ca446cab3631bb7/bofa_note.pdf
                  engine_id: docling
                  scene: document_ai
                  priority: 5
              async_llamaparse_minio_pdf:
                summary: LlamaParse async MinIO PDF parse / LlamaParse 异步解析 MinIO PDF
                description: Use this when the LlamaParse cloud API key is configured and the
                  object should be parsed by the cloud document parser.
                value:
                  sources:
                    - cortex-local/tenant_demo/obj_a3da967e3ca446cab3631bb7/bofa_note.pdf
                  engine_id: llama_parse
                  scene: document_fidelity
                  priority: 5
      responses:
        "202":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParseBatchJobAccepted"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/parse/jobs/{jobId}/result:
    get:
      tags:
        - Parse
      summary: Get a completed parse result
      description: Poll for the parse result. Returns `409` with job status until the
        parse completes, then returns the final `ParseResult`.
      operationId: getParseResult
      security:
        - BearerAuth: []
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
            description: Parse job identifier returned by `/v1/parse/jobs`.
            examples:
              - job_71fe50adf1cb4981bb322f0d74f32598
            title: Jobid
          description: Parse job identifier returned by `/v1/parse/jobs`.
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/ParseResult"
                  - $ref: "#/components/schemas/JobStatusDetail"
                title: Response Getparseresult
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatusDetail"
          description: Conflict
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/storage/uploads:
    post:
      tags:
        - Storage
      summary: Initiate an upload session
      description: Create a signed upload session for a new object. The caller
        supplies file identity plus business metadata, while Cortex infers
        content type when possible and decides whether multipart is needed.
      operationId: createUploadSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StorageUploadCreateRequest"
              description: Upload session creation request. `filename` is required. Cortex
                infers `content_type` from `filename` when omitted, uses
                `size_bytes` when available to decide single-part vs multipart,
                and manages bucket/object-key routing internally.
            examples:
              recommended_single_part:
                summary: Recommended single-part upload
                description: Best for small and medium files that fit in one signed PUT request.
                  You can omit `size_bytes`; Cortex will finalize the actual
                  object size when the upload is completed.
                value:
                  filename: README.md
                  metadata:
                    source: swagger-demo
                    document_type: guide
                  access_policy:
                    access_level: tenant_shared
                    classification_labels:
                      - internal
                    allowed_role_keys:
                      - tenant_admin
                      - analyst
                    denied_role_keys: []
                    purpose_tags:
                      - knowledge_ingest
                    constraints: {}
                  tags:
                    - docs
                    - product
              multipart_large_file:
                summary: Multipart upload for large files
                description: Recommended when the client already knows the file is large enough
                  that Cortex should initialize multipart upload and return part
                  URLs.
                value:
                  filename: quarterly-report.pdf
                  size_bytes: 67108864
                  metadata:
                    source: finance-portal
                    department: fpna
                  tags:
                    - finance
                    - quarterly
        required: true
      responses:
        "201":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StorageUploadSession"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
      security:
        - BearerAuth: []
  /v1/storage/files:
    post:
      tags:
        - Storage
      summary: Upload a small file
      description: Upload a small file directly through the Cortex API. This endpoint
        is optimized for Swagger UI, local testing, and small files; use upload
        sessions for large files or production high-throughput transfers.
      operationId: uploadSmallFile
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/Body_uploadSmallFile"
        required: true
      responses:
        "201":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StorageObject"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
      security:
        - BearerAuth: []
  /v1/storage/uploads/{uploadId}/complete:
    post:
      tags:
        - Storage
      summary: Complete an upload session
      description: Finalize a single-part or multipart upload session after the
        object-store transfer has succeeded. This step is required because
        Cortex must verify the uploaded object, recover provider metadata, and
        commit the final object/version records.
      operationId: completeUploadSession
      security:
        - BearerAuth: []
      parameters:
        - name: uploadId
          in: path
          required: true
          schema:
            type: string
            description: Upload session identifier returned by `/v1/storage/uploads`.
            examples:
              - upl_9feeaad1935f4b478ff61d6347ee5562
            title: Uploadid
          description: Upload session identifier returned by `/v1/storage/uploads`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StorageUploadCompleteRequest"
              description: Upload completion request. Use the single-part example when no
                multipart parts were issued.
            examples:
              single_part_complete:
                summary: Complete a single-part upload
                description: Use this when the upload session returned `single_part` instead of
                  `multipart_parts`.
                value:
                  parts: []
                  checksum_sha256: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
              multipart_complete:
                summary: Complete a multipart upload
                description: Send the uploaded part numbers and provider ETags exactly as
                  returned by the object store.
                value:
                  parts:
                    - part_number: 1
                      etag: '"part-1-etag"'
                    - part_number: 2
                      etag: '"part-2-etag"'
                    - part_number: 3
                      etag: '"part-3-etag"'
                    - part_number: 4
                      etag: '"part-4-etag"'
                  checksum_sha256: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StorageObject"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/storage/objects/{objectId}:
    get:
      tags:
        - Storage
      summary: Get object metadata
      description: Return the stored metadata, current version reference, and access
        policy for one object.
      operationId: getStorageObject
      security:
        - BearerAuth: []
      parameters:
        - name: objectId
          in: path
          required: true
          schema:
            type: string
            description: Storage object identifier returned by upload or search flows.
            examples:
              - obj_3f6c1d5e9b1646b5a4eabdbf8b417bd3
            title: Objectid
          description: Storage object identifier returned by upload or search flows.
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StorageObject"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/storage/objects/{objectId}/download-url:
    get:
      tags:
        - Storage
      summary: Create a download URL for an object
      description: Create a time-limited signed download URL for an object.
      operationId: createDownloadUrl
      security:
        - BearerAuth: []
      parameters:
        - name: objectId
          in: path
          required: true
          schema:
            type: string
            description: Storage object identifier to download.
            examples:
              - obj_3f6c1d5e9b1646b5a4eabdbf8b417bd3
            title: Objectid
          description: Storage object identifier to download.
        - name: ttl_seconds
          in: query
          required: false
          schema:
            type: integer
            maximum: 86400
            minimum: 60
            description: "Signed URL lifetime in seconds. Best default: 900 (15 minutes)."
            examples:
              - 900
            default: 900
            title: Ttl Seconds
          description: "Signed URL lifetime in seconds. Best default: 900 (15 minutes)."
        - name: disposition
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/DownloadDisposition"
            description: "Suggested content disposition. Best default: `attachment`; use
              `inline` for browser preview."
            examples:
              - attachment
            default: attachment
          description: "Suggested content disposition. Best default: `attachment`; use
            `inline` for browser preview."
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DownloadUrlResponse"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/synthesis/engines:
    get:
      tags:
        - Synthesis
      summary: List synthesis engines
      description: Returns the currently registered synthesis engines, supported
        synthesis types, supported source kinds, and output format hints.
      operationId: listSynthesisEngines
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SynthesisEngineList"
      security:
        - BearerAuth: []
  /v1/synthesis/sync:
    post:
      tags:
        - Synthesis
      summary: Execute a synchronous synthesis run
      description: Runs a small synthesis workload synchronously. Recommended for
        preview generation, quality-gate tuning, and low-cardinality source
        samples.
      operationId: runSynthesisSync
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SynthesisSyncRequest"
              description: "Unified synthesis request body. Required: `synthesis_type` and
                `source`. `engine_id` defaults to `auto`."
            examples:
              rag_goldens:
                summary: RAG goldens synthesis / RAG 黄金集生成
                description: Generate a small synchronous preview set of RAG golden samples from
                  documents.
                value:
                  name: Support-RAG-Goldens
                  synthesis_type: rag_goldens
                  engine_id: auto
                  source:
                    type: documents
                    documents:
                      - Cortex exposes Parse, Storage, Knowledge, Evaluation,
                        and Synthesis APIs.
                  config:
                    sample_count: 5
                    quality_gates:
                      - metric_key: quality.correctness
                        threshold: 0.8
                  output:
                    output_format: json
              sdv_single_table:
                summary: SDV single-table sync / SDV 单表同步合成
                description: Generate a small structured preview from inline records. Requires
                  the SDV runtime dependency for synchronous execution.
                value:
                  name: swagger-sdv-customers
                  synthesis_type: structured_single_table
                  engine_id: sdv
                  source:
                    type: inline_records
                    inline_records:
                      - customer_id: c1
                        tier: gold
                        monthly_spend: 1200
                      - customer_id: c2
                        tier: silver
                        monthly_spend: 300
                    options:
                      table_name: customers
                  config:
                    sample_count: 5
                    anonymize_pii: true
                    quality_gates:
                      - metric_key: quality.row_count_match
                        threshold: 1
                  output:
                    output_format: json
                    include_preview: true
              deepeval_qa_pairs:
                summary: DeepEval QA sync / DeepEval QA 同步合成
                description: Generate a tiny QA preview from inline document context.
                value:
                  name: swagger-qa-preview
                  synthesis_type: qa_pairs
                  engine_id: deepeval
                  source:
                    type: documents
                    documents:
                      - Cortex Parse turns URLs and storage objects into
                        LLM-ready Markdown.
                  config:
                    sample_count: 2
                    max_contexts_per_case: 1
                    include_expected_output: true
                  output:
                    output_format: json
                    include_preview: true
        required: true
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SynthesisRunResult"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
      security:
        - BearerAuth: []
  /v1/synthesis/jobs:
    post:
      tags:
        - Synthesis
      summary: Submit an asynchronous synthesis job
      description: Queues a longer-running synthesis workload and returns a Cortex job
        handle for polling and result retrieval.
      operationId: createSynthesisJob
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: Optional idempotency key for asynchronous synthesis job submission.
            examples:
              - parse-demo-001
            title: Idempotency-Key
          description: Optional idempotency key for asynchronous synthesis job submission.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SynthesisJobSubmitRequest"
              description: Async synthesis job request. Use this for larger synthetic dataset
                creation or batch enrichment workloads.
            examples:
              qa_pairs_job:
                summary: QA pairs synthesis job / QA 对生成作业
                description: Recommended async submission for larger synthetic dataset
                  generation workloads.
                value:
                  name: Product-QA-Synth
                  synthesis_type: qa_pairs
                  engine_id: auto
                  source:
                    type: inline_records
                    inline_records:
                      - document: Cortex supports pluggable evaluation and synthesis engines.
                  config:
                    sample_count: 100
                    quality_gates:
                      - metric_key: quality.correctness
                        threshold: 0.8
                  output:
                    output_format: jsonl
                  webhook:
                    url: https://example.com/hooks/cortex/synthesis
                    event_types:
                      - job.succeeded
                      - job.failed
              sdv_relational_job:
                summary: SDV relational async job / SDV 关系型异步合成
                description: Async relational synthesis from inline table samples. This example
                  is designed for local Swagger testing with the runtime
                  synthesis worker.
                value:
                  name: swagger-sdv-orders
                  synthesis_type: structured_relational
                  engine_id: sdv
                  source:
                    type: relational_metadata
                    options:
                      tables:
                        customers:
                          - customer_id: c1
                            tier: gold
                          - customer_id: c2
                            tier: silver
                        orders:
                          - order_id: o1
                            customer_id: c1
                            amount: 99
                          - order_id: o2
                            customer_id: c2
                            amount: 42
                  config:
                    sample_count: 3
                    anonymize_pii: true
                  output:
                    output_format: jsonl
                    include_preview: true
              deepeval_conversation_job:
                summary: DeepEval conversation async job / DeepEval 会话异步合成
                description: Async conversation golden generation from seed support-policy
                  context.
                value:
                  name: swagger-conversation-goldens
                  synthesis_type: conversation_goldens
                  engine_id: deepeval
                  source:
                    type: documents
                    documents:
                      - Support agents should ask for the object_id before
                        parsing a private file.
                  config:
                    sample_count: 3
                    max_contexts_per_case: 1
                    include_expected_output: true
                  output:
                    output_format: jsonl
                    include_preview: true
                  webhook:
                    url: https://example.com/hooks/cortex/synthesis
                    event_types:
                      - job.succeeded
                      - job.failed
      responses:
        "202":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SynthesisJobAccepted"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/synthesis/jobs/{jobId}/result:
    get:
      tags:
        - Synthesis
      summary: Get a completed synthesis result
      description: Returns the completed synthesis result when the async job succeeds,
        or a 409 job status payload while work is still in progress.
      operationId: getSynthesisResult
      security:
        - BearerAuth: []
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
            title: Jobid
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/SynthesisRunResult"
                  - $ref: "#/components/schemas/JobStatusDetail"
                title: Response Getsynthesisresult
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatusDetail"
          description: Conflict
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /v1/dev/auth/token:
    post:
      tags:
        - Dev Auth
      summary: Issue local development access token / 签发本地开发访问令牌
      description: Available only when `CORTEX_ENV=local` and `CORTEX_AUTH_MODE=dev`.
        Issues a local `dev:` bearer token for Swagger UI, curl, and smoke
        tests. This route is not mounted in non-local deployments. / 仅当
        `CORTEX_ENV=local` 且 `CORTEX_AUTH_MODE=dev` 时才会暴露。该接口用于生成本地 `dev:`
        Bearer token，便于 Swagger、curl 和冒烟测试使用；在非本地部署中不会挂载。
      operationId: issueLocalDevAccessToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LocalDevTokenIssueRequest"
              description: Local development token request. In the simplest case only
                `subject` and `tenant_id` are required. / 本地开发令牌请求，最简单时只需要填写
                `subject` 和 `tenant_id`。
            examples:
              recommended_swagger_token:
                summary: Recommended Swagger dev token / 推荐的 Swagger 开发令牌
                description: Creates a local development bearer token that can be pasted
                  directly into Swagger UI's `Authorize` dialog. / 生成一个可直接粘贴到
                  Swagger UI `Authorize` 弹窗中的本地开发 Bearer token。
                value:
                  subject: alice
                  tenant_id: tenant_demo
                  display_name: Alice
                  client_id: swagger-ui
                  roles:
                    - tenant_admin
                  groups:
                    - platform-ops
                  expires_in: 3600
              minimal_local_token:
                summary: Minimal local token request / 最小化本地令牌请求
                description: Only `subject` and `tenant_id` are required. Cortex fills in the
                  standard local developer scopes automatically. / 只需要 `subject`
                  和 `tenant_id`，其余标准本地开发 scope 由 Cortex 自动补齐。
                value:
                  subject: smoke-test
                  tenant_id: tenant_demo
        required: true
      responses:
        "200":
          description: Local development token issued. / 已签发本地开发令牌。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LocalDevTokenIssueResponse"
        "422":
          description: Validation error. / 请求体验证失败。
components:
  schemas:
    AccessLevel:
      type: string
      enum:
        - tenant_private
        - tenant_shared
        - restricted
        - confidential
      title: AccessLevel
    AccessPolicy:
      properties:
        access_level:
          anyOf:
            - $ref: "#/components/schemas/AccessLevel"
            - type: "null"
          description: "Optional coarse-grained data access level. Best default: omit to
            let the service apply the resource-type default."
          examples:
            - tenant_shared
        owner_actor_id:
          anyOf:
            - type: string
            - type: "null"
          title: Owner Actor Id
          description: "Optional resource owner actor ID. Best default: omit to let the
            service infer ownership from the caller."
          examples:
            - alice
        classification_labels:
          items:
            type: string
          type: array
          title: Classification Labels
          description: "Optional classification labels such as `internal` or `restricted`.
            Best default: empty list."
          examples:
            - - internal
              - docs
        allowed_role_keys:
          items:
            type: string
          type: array
          title: Allowed Role Keys
          description: "Optional allow-list of roles that may access the resource. Best
            default: empty list, meaning no extra allow-list constraint."
          examples:
            - - tenant_admin
              - analyst
        denied_role_keys:
          items:
            type: string
          type: array
          title: Denied Role Keys
          description: "Optional deny-list of roles that should be blocked even if other
            checks pass. Best default: empty list."
          examples:
            - - contractor
        purpose_tags:
          items:
            type: string
          type: array
          title: Purpose Tags
          description: "Optional intended-use tags for ABAC policy evaluation. Best
            default: empty list."
          examples:
            - - knowledge_ingest
              - assistant
        constraints:
          additionalProperties: true
          type: object
          title: Constraints
          description: "Optional structured constraints for custom policy engines. Best
            default: empty object."
          examples:
            - region: cn-shanghai
      type: object
      title: AccessPolicy
    AddJobRequest:
      properties:
        dataset_id:
          anyOf:
            - type: string
            - type: "null"
          title: Dataset Id
          description: Optional dataset ID. Provide either `dataset_id` or `dataset_key`.
          examples:
            - dset_9558cfc9178444e4a4c60d5658db78f5
        dataset_key:
          anyOf:
            - type: string
            - type: "null"
          title: Dataset Key
          description: Optional dataset key. Recommended for human-authored requests when
            stable keys are known.
          examples:
            - product_docs
        inputs:
          items:
            $ref: "#/components/schemas/KnowledgeInput"
          type: array
          minItems: 1
          title: Inputs
          description: Required ingest inputs. At least one input is required.
        options:
          $ref: "#/components/schemas/AddOptions"
          description: "Optional ingest behavior flags. Best default: use the built-in
            defaults."
        webhook:
          anyOf:
            - $ref: "#/components/schemas/WebhookConfig"
            - type: "null"
          description: "Optional webhook callback for job lifecycle events. Best default:
            omit."
      type: object
      required:
        - inputs
      title: AddJobRequest
    AddOptions:
      properties:
        normalize_text:
          type: boolean
          title: Normalize Text
          description: "Normalize raw text before ingestion. Best default: `true`."
          default: true
        structured_ingest:
          type: boolean
          title: Structured Ingest
          description: "Enable structured ingestion and field extraction. Best default:
            `true`."
          default: true
        incremental:
          type: boolean
          title: Incremental
          description: "Avoid reprocessing unchanged content when possible. Best default:
            `true`."
          default: true
        persist_source_copy:
          type: boolean
          title: Persist Source Copy
          description: "Persist a copy of the source payload when supported. Best default:
            `true`."
          default: true
      type: object
      title: AddOptions
    AppliedParseEngine:
      properties:
        engine_key:
          anyOf:
            - type: string
            - type: "null"
          title: Engine Key
        display_name:
          anyOf:
            - type: string
            - type: "null"
          title: Display Name
        engine_family:
          anyOf:
            - type: string
            - type: "null"
          title: Engine Family
        engine_version:
          anyOf:
            - type: string
            - type: "null"
          title: Engine Version
        profile_ref:
          anyOf:
            - type: string
            - type: "null"
          title: Profile Ref
        template_ref:
          anyOf:
            - type: string
            - type: "null"
          title: Template Ref
        fallback_used:
          type: boolean
          title: Fallback Used
          default: false
      type: object
      title: AppliedParseEngine
    AuditFields:
      properties:
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        created_by:
          anyOf:
            - type: string
            - type: "null"
          title: Created By
        updated_by:
          anyOf:
            - type: string
            - type: "null"
          title: Updated By
      type: object
      required:
        - created_at
        - updated_at
      title: AuditFields
    Body_uploadSmallFile:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
          description: File content to upload. Cortex derives filename, content type, and
            size from the multipart part.
        metadata_json:
          anyOf:
            - type: string
            - type: "null"
          title: Metadata Json
          description: "Optional JSON object string for object metadata. Best default:
            `{}`."
          examples:
            - '{"source":"swagger-demo","document_type":"guide"}'
        access_policy_json:
          anyOf:
            - type: string
            - type: "null"
          title: Access Policy Json
          description: "Optional JSON object string matching AccessPolicy. Best default:
            omit for tenant_private."
          examples:
            - '{"access_level":"tenant_shared"}'
        tags:
          anyOf:
            - type: string
            - type: "null"
          title: Tags
          description: "Optional comma-separated tags or JSON array string. Best default:
            empty."
          examples:
            - docs,product
        checksum_sha256:
          anyOf:
            - type: string
              pattern: ^[0-9a-f]{64}$
            - type: "null"
          title: Checksum Sha256
          description: Optional lowercase SHA-256 checksum. Cortex verifies it before
            committing object metadata when provided.
          examples:
            - aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
      type: object
      required:
        - file
      title: Body_uploadSmallFile
    ChunkingOptions:
      properties:
        enabled:
          type: boolean
          title: Enabled
          description: "Whether Cortex should emit chunking hints or stored chunks. Best
            default: `true`."
          default: true
        strategy:
          $ref: "#/components/schemas/ChunkingStrategy"
          description: "Chunking strategy. Best default: `semantic` for LLM-ready content."
          default: semantic
        target_tokens:
          type: integer
          maximum: 4096
          minimum: 64
          title: Target Tokens
          description: "Target token count per chunk. Best default: 512."
          default: 512
          examples:
            - 512
        overlap_tokens:
          type: integer
          maximum: 1024
          minimum: 0
          title: Overlap Tokens
          description: "Token overlap between adjacent chunks. Best default: 64."
          default: 64
          examples:
            - 64
        max_chunks:
          type: integer
          maximum: 10000
          minimum: 1
          title: Max Chunks
          description: "Maximum chunks emitted for one document. Best default: 256."
          default: 256
          examples:
            - 256
      type: object
      title: ChunkingOptions
    ChunkingStrategy:
      type: string
      enum:
        - none
        - heading
        - semantic
        - fixed_tokens
      title: ChunkingStrategy
    Citation:
      properties:
        source_url:
          anyOf:
            - type: string
            - type: "null"
          title: Source Url
        document_id:
          anyOf:
            - type: string
            - type: "null"
          title: Document Id
        chunk_id:
          anyOf:
            - type: string
            - type: "null"
          title: Chunk Id
        start_offset:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Start Offset
        end_offset:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: End Offset
      type: object
      title: Citation
    CognifyJobRequest:
      properties:
        dataset_id:
          anyOf:
            - type: string
            - type: "null"
          title: Dataset Id
          description: Optional dataset ID. Provide either `dataset_id` or `dataset_key`.
          examples:
            - dset_9558cfc9178444e4a4c60d5658db78f5
        dataset_key:
          anyOf:
            - type: string
            - type: "null"
          title: Dataset Key
          description: Optional dataset key. Recommended when stable dataset keys are known.
          examples:
            - product_docs
        incremental_loading:
          type: boolean
          title: Incremental Loading
          description: "Only process newly added or changed content when possible. Best
            default: `true`."
          default: true
        graph_prompt_profile:
          $ref: "#/components/schemas/GraphPromptProfile"
          description: "Prompt profile for graph extraction. Best default: `default`."
          default: default
        chunking:
          $ref: "#/components/schemas/ChunkingOptions"
          description: Chunking controls used before graph creation.
        webhook:
          anyOf:
            - $ref: "#/components/schemas/WebhookConfig"
            - type: "null"
          description: "Optional webhook callback. Best default: omit."
      type: object
      title: CognifyJobRequest
    CompletedUploadPart:
      properties:
        part_number:
          type: integer
          minimum: 1
          title: Part Number
          description: Multipart part number exactly as returned during upload session
            creation.
          examples:
            - 1
        etag:
          type: string
          title: Etag
          description: ETag returned by the object store after uploading the part.
          examples:
            - '"part-1-etag"'
      type: object
      required:
        - part_number
        - etag
      title: CompletedUploadPart
    DatasetCounters:
      properties:
        objects:
          type: integer
          minimum: 0
          title: Objects
          default: 0
        documents:
          type: integer
          minimum: 0
          title: Documents
          default: 0
        chunks:
          type: integer
          minimum: 0
          title: Chunks
          default: 0
        graph_nodes:
          type: integer
          minimum: 0
          title: Graph Nodes
          default: 0
        graph_edges:
          type: integer
          minimum: 0
          title: Graph Edges
          default: 0
      type: object
      title: DatasetCounters
    DatasetRetentionClass:
      type: string
      enum:
        - standard
        - durable
        - temporary
      title: DatasetRetentionClass
    DependencyCheck:
      properties:
        name:
          type: string
          title: Name
        status:
          type: string
          title: Status
        latency_ms:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Latency Ms
        detail:
          anyOf:
            - type: string
            - type: "null"
          title: Detail
      type: object
      required:
        - name
        - status
      title: DependencyCheck
    DocumentProvenance:
      properties:
        input_kind:
          anyOf:
            - $ref: "#/components/schemas/ParseInputKind"
            - type: "null"
        fetched_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Fetched At
        final_url:
          anyOf:
            - type: string
            - type: "null"
          title: Final Url
        http_status:
          anyOf:
            - type: integer
              maximum: 599
              minimum: 100
            - type: "null"
          title: Http Status
        content_length_bytes:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Content Length Bytes
        parser_version:
          anyOf:
            - type: string
            - type: "null"
          title: Parser Version
        content_hash_sha256:
          anyOf:
            - type: string
              pattern: ^[0-9a-f]{64}$
            - type: "null"
          title: Content Hash Sha256
      type: object
      title: DocumentProvenance
    DownloadDisposition:
      type: string
      enum:
        - attachment
        - inline
      title: DownloadDisposition
    DownloadUrlResponse:
      properties:
        object_id:
          type: string
          title: Object Id
        method:
          type: string
          title: Method
        url:
          type: string
          title: Url
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
        expires_at:
          type: string
          format: date-time
          title: Expires At
      type: object
      required:
        - object_id
        - method
        - url
        - expires_at
      title: DownloadUrlResponse
    EngineMetricBinding:
      properties:
        engine_id:
          type: string
          title: Engine Id
        native_key:
          anyOf:
            - type: string
            - type: "null"
          title: Native Key
        notes:
          anyOf:
            - type: string
            - type: "null"
          title: Notes
      type: object
      required:
        - engine_id
      title: EngineMetricBinding
    EvalConversationTurn:
      properties:
        role:
          type: string
          title: Role
        content:
          type: string
          title: Content
      type: object
      required:
        - role
        - content
      title: EvalConversationTurn
    EvalEngineDescriptor:
      properties:
        engine_id:
          type: string
          title: Engine Id
        display_name:
          type: string
          title: Display Name
        availability_status:
          type: string
          pattern: ^(available|degraded|disabled)$
          title: Availability Status
        provider:
          anyOf:
            - type: string
            - type: "null"
          title: Provider
        execution_modes:
          items:
            type: string
          type: array
          title: Execution Modes
        supported_eval_types:
          items:
            $ref: "#/components/schemas/EvalType"
          type: array
          title: Supported Eval Types
        supported_metric_prefixes:
          items:
            type: string
          type: array
          title: Supported Metric Prefixes
        default_profiles:
          items:
            type: string
          type: array
          title: Default Profiles
        notes:
          anyOf:
            - type: string
            - type: "null"
          title: Notes
      type: object
      required:
        - engine_id
        - display_name
        - availability_status
      title: EvalEngineDescriptor
    EvalEngineList:
      properties:
        generated_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Generated At
        engines:
          items:
            $ref: "#/components/schemas/EvalEngineDescriptor"
          type: array
          title: Engines
      type: object
      required:
        - engines
      title: EvalEngineList
    EvalFieldMapping:
      properties:
        user_input:
          anyOf:
            - type: string
            - type: "null"
          title: User Input
        actual_output:
          anyOf:
            - type: string
            - type: "null"
          title: Actual Output
        expected_output:
          anyOf:
            - type: string
            - type: "null"
          title: Expected Output
        retrieval_contexts:
          anyOf:
            - type: string
            - type: "null"
          title: Retrieval Contexts
        conversation_turns:
          anyOf:
            - type: string
            - type: "null"
          title: Conversation Turns
      type: object
      title: EvalFieldMapping
    EvalInput:
      properties:
        type:
          type: string
          title: Type
        dataset_id:
          anyOf:
            - type: string
            - type: "null"
          title: Dataset Id
        dataset_version:
          anyOf:
            - type: string
            - type: "null"
          title: Dataset Version
        builtin_dataset_key:
          anyOf:
            - type: string
            - type: "null"
          title: Builtin Dataset Key
        object_id:
          anyOf:
            - type: string
            - type: "null"
          title: Object Id
        object_ids:
          items:
            type: string
          type: array
          title: Object Ids
        field_mapping:
          anyOf:
            - $ref: "#/components/schemas/EvalFieldMapping"
            - type: "null"
        filters:
          additionalProperties: true
          type: object
          title: Filters
        test_cases:
          items:
            $ref: "#/components/schemas/EvalTestCase"
          type: array
          title: Test Cases
        trace_session_id:
          anyOf:
            - type: string
            - type: "null"
          title: Trace Session Id
      type: object
      required:
        - type
      title: EvalInput
    EvalJobAccepted:
      properties:
        job_id:
          type: string
          title: Job Id
        job_type:
          $ref: "#/components/schemas/JobType"
        status:
          $ref: "#/components/schemas/JobStatus"
        submitted_at:
          type: string
          format: date-time
          title: Submitted At
        poll_url:
          type: string
          title: Poll Url
        result_url:
          anyOf:
            - type: string
            - type: "null"
          title: Result Url
        cancel_url:
          anyOf:
            - type: string
            - type: "null"
          title: Cancel Url
        telemetry:
          anyOf:
            - $ref: "#/components/schemas/TelemetryContext"
            - type: "null"
        eval_type:
          anyOf:
            - $ref: "#/components/schemas/EvalType"
            - type: "null"
        engine_id:
          anyOf:
            - type: string
            - type: "null"
          title: Engine Id
      type: object
      required:
        - job_id
        - job_type
        - status
        - submitted_at
        - poll_url
      title: EvalJobAccepted
    EvalJobSubmitRequest:
      properties:
        eval_type:
          $ref: "#/components/schemas/EvalType"
        input:
          $ref: "#/components/schemas/EvalInput"
        name:
          anyOf:
            - type: string
            - type: "null"
          title: Name
        engine_id:
          type: string
          title: Engine Id
          default: auto
        profile_key:
          anyOf:
            - type: string
            - type: "null"
          title: Profile Key
        target:
          anyOf:
            - $ref: "#/components/schemas/EvalTarget"
            - type: "null"
        metrics:
          items:
            $ref: "#/components/schemas/EvalMetricRequest"
          type: array
          title: Metrics
        engine_options:
          additionalProperties: true
          type: object
          title: Engine Options
        output:
          $ref: "#/components/schemas/EvalOutputOptions"
        webhook:
          anyOf:
            - $ref: "#/components/schemas/WebhookConfig"
            - type: "null"
      type: object
      required:
        - eval_type
        - input
      title: EvalJobSubmitRequest
    EvalMetricCatalog:
      properties:
        generated_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Generated At
        metrics:
          items:
            $ref: "#/components/schemas/EvalMetricDefinition"
          type: array
          title: Metrics
      type: object
      required:
        - metrics
      title: EvalMetricCatalog
    EvalMetricDefinition:
      properties:
        metric_key:
          type: string
          title: Metric Key
        display_name:
          type: string
          title: Display Name
        eval_types:
          items:
            $ref: "#/components/schemas/EvalType"
          type: array
          title: Eval Types
        engine_bindings:
          items:
            $ref: "#/components/schemas/EngineMetricBinding"
          type: array
          title: Engine Bindings
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        category:
          anyOf:
            - type: string
            - type: "null"
          title: Category
        unit:
          anyOf:
            - type: string
            - type: "null"
          title: Unit
        score_direction:
          type: string
          title: Score Direction
          default: higher_is_better
        threshold_hint:
          anyOf:
            - type: number
            - type: "null"
          title: Threshold Hint
        required_fields:
          items:
            type: string
          type: array
          title: Required Fields
      type: object
      required:
        - metric_key
        - display_name
      title: EvalMetricDefinition
    EvalMetricRequest:
      properties:
        metric_key:
          type: string
          title: Metric Key
        threshold:
          anyOf:
            - type: number
            - type: "null"
          title: Threshold
        weight:
          anyOf:
            - type: number
            - type: "null"
          title: Weight
        params:
          additionalProperties: true
          type: object
          title: Params
      type: object
      required:
        - metric_key
      title: EvalMetricRequest
    EvalMetricResult:
      properties:
        metric_key:
          type: string
          title: Metric Key
        status:
          type: string
          pattern: ^(passed|failed|warn|info)$
          title: Status
        display_name:
          anyOf:
            - type: string
            - type: "null"
          title: Display Name
        score:
          anyOf:
            - type: number
            - type: "null"
          title: Score
        threshold:
          anyOf:
            - type: number
            - type: "null"
          title: Threshold
        unit:
          anyOf:
            - type: string
            - type: "null"
          title: Unit
        engine_id:
          anyOf:
            - type: string
            - type: "null"
          title: Engine Id
        native_metric_key:
          anyOf:
            - type: string
            - type: "null"
          title: Native Metric Key
        sample_size:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Sample Size
        details:
          additionalProperties: true
          type: object
          title: Details
      type: object
      required:
        - metric_key
        - status
      title: EvalMetricResult
    EvalOutputOptions:
      properties:
        persist_report_object:
          type: boolean
          title: Persist Report Object
          default: true
        persist_dataset_key:
          anyOf:
            - type: string
            - type: "null"
          title: Persist Dataset Key
        include_sample_results:
          type: boolean
          title: Include Sample Results
          default: true
        max_failures_reported:
          anyOf:
            - type: integer
              minimum: 1
            - type: "null"
          title: Max Failures Reported
      type: object
      title: EvalOutputOptions
    EvalRunResult:
      properties:
        eval_type:
          $ref: "#/components/schemas/EvalType"
        engine_id:
          type: string
          title: Engine Id
        status:
          type: string
          pattern: ^(succeeded|failed|partial)$
          title: Status
        summary:
          $ref: "#/components/schemas/EvalScoreCard"
        metrics:
          items:
            $ref: "#/components/schemas/EvalMetricResult"
          type: array
          title: Metrics
        eval_run_id:
          anyOf:
            - type: string
            - type: "null"
          title: Eval Run Id
        job_id:
          anyOf:
            - type: string
            - type: "null"
          title: Job Id
        name:
          anyOf:
            - type: string
            - type: "null"
          title: Name
        profile_key:
          anyOf:
            - type: string
            - type: "null"
          title: Profile Key
        source_summary:
          additionalProperties: true
          type: object
          title: Source Summary
        target_summary:
          additionalProperties: true
          type: object
          title: Target Summary
        samples:
          anyOf:
            - $ref: "#/components/schemas/EvalSampleCounters"
            - type: "null"
        artifacts:
          items:
            $ref: "#/components/schemas/StoredArtifactRef"
          type: array
          title: Artifacts
        telemetry:
          anyOf:
            - $ref: "#/components/schemas/TelemetryContext"
            - type: "null"
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Started At
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Completed At
      type: object
      required:
        - eval_type
        - engine_id
        - status
        - summary
        - metrics
      title: EvalRunResult
    EvalSampleCounters:
      properties:
        total:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Total
        passed:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Passed
        failed:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Failed
        skipped:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Skipped
      type: object
      title: EvalSampleCounters
    EvalScoreCard:
      properties:
        overall_passed:
          type: boolean
          title: Overall Passed
        composite_score:
          anyOf:
            - type: number
            - type: "null"
          title: Composite Score
        metric_count:
          type: integer
          minimum: 0
          title: Metric Count
          default: 0
        passed_metric_count:
          type: integer
          minimum: 0
          title: Passed Metric Count
          default: 0
        failed_metric_count:
          type: integer
          minimum: 0
          title: Failed Metric Count
          default: 0
        summary_by_namespace:
          additionalProperties:
            type: number
          type: object
          title: Summary By Namespace
      type: object
      required:
        - overall_passed
      title: EvalScoreCard
    EvalSyncRequest:
      properties:
        eval_type:
          $ref: "#/components/schemas/EvalType"
        input:
          $ref: "#/components/schemas/EvalInput"
        name:
          anyOf:
            - type: string
            - type: "null"
          title: Name
        engine_id:
          type: string
          title: Engine Id
          default: auto
        profile_key:
          anyOf:
            - type: string
            - type: "null"
          title: Profile Key
        target:
          anyOf:
            - $ref: "#/components/schemas/EvalTarget"
            - type: "null"
        metrics:
          items:
            $ref: "#/components/schemas/EvalMetricRequest"
          type: array
          title: Metrics
        engine_options:
          additionalProperties: true
          type: object
          title: Engine Options
        output:
          $ref: "#/components/schemas/EvalOutputOptions"
        webhook:
          anyOf:
            - $ref: "#/components/schemas/WebhookConfig"
            - type: "null"
      type: object
      required:
        - eval_type
        - input
      title: EvalSyncRequest
    EvalTarget:
      properties:
        type:
          type: string
          title: Type
        protocol:
          anyOf:
            - type: string
            - type: "null"
          title: Protocol
        endpoint_url:
          anyOf:
            - type: string
            - type: "null"
          title: Endpoint Url
        auth_ref:
          anyOf:
            - type: string
            - type: "null"
          title: Auth Ref
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
        timeout_seconds:
          anyOf:
            - type: integer
              minimum: 1
            - type: "null"
          title: Timeout Seconds
        model_ref:
          anyOf:
            - type: string
            - type: "null"
          title: Model Ref
        provider:
          anyOf:
            - type: string
            - type: "null"
          title: Provider
        request_template:
          additionalProperties: true
          type: object
          title: Request Template
      type: object
      required:
        - type
      title: EvalTarget
    EvalTestCase:
      properties:
        user_input:
          anyOf:
            - type: string
            - type: "null"
          title: User Input
        actual_output:
          anyOf:
            - type: string
            - type: "null"
          title: Actual Output
        expected_output:
          anyOf:
            - type: string
            - type: "null"
          title: Expected Output
        retrieval_contexts:
          items:
            type: string
          type: array
          title: Retrieval Contexts
        conversation_turns:
          items:
            $ref: "#/components/schemas/EvalConversationTurn"
          type: array
          title: Conversation Turns
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      type: object
      title: EvalTestCase
    EvalType:
      type: string
      enum:
        - perf
        - rag
        - agentic
        - multi_turn
        - custom
      title: EvalType
    FallbackMode:
      type: string
      enum:
        - none
        - ordered
        - capability_based
        - quality_based
      title: FallbackMode
    FallbackOnError:
      type: string
      enum:
        - try_next
        - fail_fast
      title: FallbackOnError
    FallbackPolicy:
      properties:
        enabled:
          type: boolean
          title: Enabled
          description: Whether Cortex may try another parser engine after the preferred one.
          default: true
        mode:
          $ref: "#/components/schemas/FallbackMode"
          description: "Fallback strategy. Best default: `ordered` for predictable adapter
            order."
          default: ordered
        on_error:
          $ref: "#/components/schemas/FallbackOnError"
          description: "How to react when an engine fails. Best default: `try_next`."
          default: try_next
        max_engine_attempts:
          type: integer
          maximum: 10
          minimum: 1
          title: Max Engine Attempts
          description: "Maximum number of engine attempts before the parse run fails. Best
            default: 3."
          default: 3
          examples:
            - 3
      type: object
      title: FallbackPolicy
    GraphPath:
      properties:
        nodes:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Nodes
        edges:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Edges
      type: object
      title: GraphPath
    GraphPromptProfile:
      type: string
      enum:
        - default
        - simple
        - strict
        - guided
      title: GraphPromptProfile
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: "#/components/schemas/ValidationError"
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    HealthResponse:
      properties:
        status:
          type: string
          title: Status
        service:
          type: string
          title: Service
        mode:
          type: string
          title: Mode
        version:
          type: string
          title: Version
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        checks:
          items:
            $ref: "#/components/schemas/DependencyCheck"
          type: array
          title: Checks
      type: object
      required:
        - status
        - service
        - mode
        - version
        - timestamp
      title: HealthResponse
    JobAccepted:
      properties:
        job_id:
          type: string
          title: Job Id
        job_type:
          $ref: "#/components/schemas/JobType"
        status:
          $ref: "#/components/schemas/JobStatus"
        submitted_at:
          type: string
          format: date-time
          title: Submitted At
        poll_url:
          type: string
          title: Poll Url
        result_url:
          anyOf:
            - type: string
            - type: "null"
          title: Result Url
        cancel_url:
          anyOf:
            - type: string
            - type: "null"
          title: Cancel Url
        telemetry:
          anyOf:
            - $ref: "#/components/schemas/TelemetryContext"
            - type: "null"
      type: object
      required:
        - job_id
        - job_type
        - status
        - submitted_at
        - poll_url
      title: JobAccepted
    JobError:
      properties:
        code:
          anyOf:
            - type: string
            - type: "null"
          title: Code
        message:
          anyOf:
            - type: string
            - type: "null"
          title: Message
      type: object
      title: JobError
    JobEvent:
      properties:
        sequence:
          type: integer
          minimum: 1
          title: Sequence
        level:
          type: string
          title: Level
        event_type:
          type: string
          title: Event Type
        event_at:
          type: string
          format: date-time
          title: Event At
        message:
          anyOf:
            - type: string
            - type: "null"
          title: Message
        details:
          additionalProperties: true
          type: object
          title: Details
        telemetry:
          anyOf:
            - $ref: "#/components/schemas/TelemetryContext"
            - type: "null"
      type: object
      required:
        - sequence
        - level
        - event_type
        - event_at
      title: JobEvent
    JobMetrics:
      properties:
        queue_latency_ms:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Queue Latency Ms
        run_latency_ms:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Run Latency Ms
      type: object
      title: JobMetrics
    JobStatus:
      type: string
      enum:
        - queued
        - running
        - succeeded
        - failed
        - cancelled
      title: JobStatus
    JobStatusDetail:
      properties:
        job_id:
          type: string
          title: Job Id
        job_type:
          $ref: "#/components/schemas/JobType"
        status:
          $ref: "#/components/schemas/JobStatus"
        operation_name:
          type: string
          title: Operation Name
        submitted_at:
          type: string
          format: date-time
          title: Submitted At
        progress_percent:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: "null"
          title: Progress Percent
        queue_name:
          anyOf:
            - type: string
            - type: "null"
          title: Queue Name
        target_type:
          anyOf:
            - type: string
            - type: "null"
          title: Target Type
        target_id:
          anyOf:
            - type: string
            - type: "null"
          title: Target Id
        correlation_id:
          anyOf:
            - type: string
            - type: "null"
          title: Correlation Id
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Started At
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Completed At
        error:
          anyOf:
            - $ref: "#/components/schemas/JobError"
            - type: "null"
        metrics:
          anyOf:
            - $ref: "#/components/schemas/JobMetrics"
            - type: "null"
        telemetry:
          anyOf:
            - $ref: "#/components/schemas/TelemetryContext"
            - type: "null"
      type: object
      required:
        - job_id
        - job_type
        - status
        - operation_name
        - submitted_at
      title: JobStatusDetail
    JobType:
      type: string
      enum:
        - parse
        - knowledge_add
        - knowledge_cognify
        - knowledge_memify
        - eval
        - synthesis
      title: JobType
    KnowledgeDataset:
      properties:
        dataset_id:
          type: string
          title: Dataset Id
        dataset_key:
          type: string
          title: Dataset Key
        display_name:
          type: string
          title: Display Name
        status:
          $ref: "#/components/schemas/KnowledgeDatasetStatus"
        audit:
          $ref: "#/components/schemas/AuditFields"
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        tags:
          items:
            type: string
          type: array
          title: Tags
        retention_class:
          $ref: "#/components/schemas/DatasetRetentionClass"
          default: standard
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        access_policy:
          anyOf:
            - $ref: "#/components/schemas/AccessPolicy"
            - type: "null"
        counters:
          $ref: "#/components/schemas/DatasetCounters"
      type: object
      required:
        - dataset_id
        - dataset_key
        - display_name
        - status
        - audit
      title: KnowledgeDataset
    KnowledgeDatasetCreateRequest:
      properties:
        dataset_key:
          type: string
          pattern: ^[a-z0-9][a-z0-9_-]{1,126}$
          title: Dataset Key
          description: Required stable dataset key. Use lowercase letters, digits,
            underscores, or hyphens.
          examples:
            - product_docs
        display_name:
          type: string
          title: Display Name
          description: Required human-friendly dataset name.
          examples:
            - Product Docs
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
          description: "Optional dataset description. Best default: omit."
          examples:
            - Primary product knowledge base for demos and regression tests.
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: "Optional dataset tags. Best default: empty list."
          examples:
            - - docs
              - product
        retention_class:
          $ref: "#/components/schemas/DatasetRetentionClass"
          description: "Retention profile. Best default: `standard`."
          default: standard
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: "Optional dataset metadata. Best default: empty object."
          examples:
            - domain: product
              owner_team: platform
        access_policy:
          anyOf:
            - $ref: "#/components/schemas/AccessPolicy"
            - type: "null"
          description: "Optional access policy attached to the dataset. Best default: omit."
      type: object
      required:
        - dataset_key
        - display_name
      title: KnowledgeDatasetCreateRequest
    KnowledgeDatasetStatus:
      type: string
      enum:
        - active
        - archived
        - deleting
      title: KnowledgeDatasetStatus
    KnowledgeInput:
      properties:
        input_type:
          $ref: "#/components/schemas/KnowledgeInputType"
          description: Required input type. It determines which of `object_id`,
            `document_id`, `text`, or `uri` must be set.
          examples:
            - document_id
        object_id:
          anyOf:
            - type: string
            - type: "null"
          title: Object Id
          description: "Storage object ID when `input_type=object_id`. Best default: omit."
          examples:
            - obj_3f6c1d5e9b1646b5a4eabdbf8b417bd3
        document_id:
          anyOf:
            - type: string
            - type: "null"
          title: Document Id
          description: "Parsed document ID when `input_type=document_id`. Best default:
            omit."
          examples:
            - doc_71fe50adf1cb4981bb322f0d74f32598
        text:
          anyOf:
            - type: string
            - type: "null"
          title: Text
          description: "Inline text when `input_type=text`. Best default: omit."
          examples:
            - |-
              # Cortex Notes

              Cortex supports Parse, Storage, and Knowledge APIs.
        uri:
          anyOf:
            - type: string
            - type: "null"
          title: Uri
          description: "External URI when `input_type=uri`. Best default: omit."
          examples:
            - https://example.com/knowledge-source.md
        label:
          anyOf:
            - type: string
            - type: "null"
          title: Label
          description: "Optional label for operators and observability. Best default: omit."
          examples:
            - Normalized parsed document
        node_set:
          items:
            type: string
          type: array
          title: Node Set
          description: "Optional node-set grouping tags. Best default: empty list."
          examples:
            - - docs
              - parsed
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: "Optional input metadata copied into downstream processing. Best
            default: empty object."
          examples:
            - source: parse
      type: object
      required:
        - input_type
      title: KnowledgeInput
    KnowledgeInputType:
      type: string
      enum:
        - object_id
        - document_id
        - text
        - uri
      title: KnowledgeInputType
    LocalDevTokenIssueRequest:
      properties:
        subject:
          type: string
          maxLength: 255
          minLength: 1
          title: Subject
          description: Required subject identifier for the local development caller. /
            本地开发调用方的必填主体标识。
          examples:
            - alice
        tenant_id:
          type: string
          maxLength: 255
          minLength: 1
          title: Tenant Id
          description: Required tenant boundary that Cortex will apply to the issued
            token. / Cortex 将应用到令牌上的必填租户边界。
          examples:
            - tenant_demo
        actor_id:
          anyOf:
            - type: string
              maxLength: 255
              minLength: 1
            - type: "null"
          title: Actor Id
          description: "Optional actor identifier when it differs from `subject`. Best
            default: omit and let Cortex fall back to `subject`. / 可选 actor
            标识；若与 `subject` 相同，最佳默认值为省略。"
          examples:
            - alice
        actor_ref:
          anyOf:
            - type: string
              maxLength: 320
              minLength: 1
            - type: "null"
          title: Actor Ref
          description: "Optional external reference such as email or employee number. Best
            default: omit when no external directory reference exists. /
            可选外部引用，如邮箱或工号；若不存在外部目录引用，最佳默认值为省略。"
          examples:
            - alice@example.com
        actor_type:
          type: string
          maxLength: 64
          minLength: 1
          title: Actor Type
          description: "Optional actor category. Best default: `user`. / 可选 actor
            类型，最佳默认值为 `user`。"
          default: user
          examples:
            - user
            - service
        display_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: "null"
          title: Display Name
          description: Optional human-friendly display name copied into the dev token. /
            可选展示名，会复制到 dev token 中。
          examples:
            - Alice
        client_id:
          anyOf:
            - type: string
              maxLength: 255
              minLength: 1
            - type: "null"
          title: Client Id
          description: Optional client identifier for the local tool or UI issuing
            requests. / 可选本地工具或 UI 的 client 标识。
          examples:
            - swagger-ui
        scopes:
          items:
            type: string
          type: array
          title: Scopes
          description: "Optional scopes granted to the local dev token. Best default: omit
            and let Cortex issue the standard local developer scope bundle. / 可选
            scope 集合，最佳默认值为省略，让 Cortex 自动填入标准本地开发 scope 包。"
          examples:
            - - health:read
              - parse:write
              - jobs:read
        roles:
          items:
            type: string
          type: array
          title: Roles
          description: "Optional role keys attached to the caller. Best default: empty
            list. / 可选角色键集合，最佳默认值为空列表。"
          examples:
            - - tenant_admin
        groups:
          items:
            type: string
          type: array
          title: Groups
          description: Optional group memberships used by downstream policy logic. /
            可选分组信息，供下游策略判断使用。
          examples:
            - - platform-ops
        expires_in:
          type: integer
          maximum: 604800
          minimum: 60
          title: Expires In
          description: "Optional token TTL in seconds. Best default: `3600` for local
            Swagger and smoke tests. / 可选令牌有效期，单位为秒；本地 Swagger 与冒烟测试的最佳默认值为
            `3600`。"
          default: 3600
          examples:
            - 3600
        additional_claims:
          additionalProperties: true
          type: object
          title: Additional Claims
          description: Optional extra claims copied into the dev token payload. / 可选额外
            claim，会复制到 dev token 载荷中。
          examples:
            - environment: local
      additionalProperties: false
      type: object
      required:
        - subject
        - tenant_id
      title: LocalDevTokenIssueRequest
    LocalDevTokenIssueResponse:
      properties:
        access_token:
          type: string
          title: Access Token
        token_type:
          type: string
          const: Bearer
          title: Token Type
          default: Bearer
        token_format:
          type: string
          const: dev
          title: Token Format
          default: dev
        expires_in:
          type: integer
          minimum: 1
          title: Expires In
        issued_at:
          type: string
          format: date-time
          title: Issued At
        expires_at:
          type: string
          format: date-time
          title: Expires At
        scope:
          type: string
          title: Scope
        subject:
          type: string
          title: Subject
        tenant_id:
          type: string
          title: Tenant Id
        issuer:
          type: string
          title: Issuer
        audience:
          type: string
          title: Audience
        swagger_authorize_value:
          type: string
          title: Swagger Authorize Value
          description: Paste this exact value into Swagger UI's `Authorize` dialog. Do not
            prepend `Bearer ` manually. / 将这个值原样粘贴到 Swagger UI 的 `Authorize`
            弹窗中，不要手动再加 `Bearer ` 前缀。
        authorization_header:
          type: string
          title: Authorization Header
          description: Ready-to-use HTTP Authorization header value for curl, Postman, or
            SDK tests. / 可直接用于 curl、Postman 或 SDK 测试的完整 Authorization 头。
      type: object
      required:
        - access_token
        - expires_in
        - issued_at
        - expires_at
        - scope
        - subject
        - tenant_id
        - issuer
        - audience
        - swagger_authorize_value
        - authorization_header
      title: LocalDevTokenIssueResponse
    MemifyJobRequest:
      properties:
        dataset_id:
          anyOf:
            - type: string
            - type: "null"
          title: Dataset Id
          description: Optional dataset ID. Provide either `dataset_id` or `dataset_key`.
          examples:
            - dset_9558cfc9178444e4a4c60d5658db78f5
        dataset_key:
          anyOf:
            - type: string
            - type: "null"
          title: Dataset Key
          description: Optional dataset key. Recommended for copy-paste requests.
          examples:
            - product_docs
        pipeline:
          $ref: "#/components/schemas/MemifyPipeline"
          description: "Memify enrichment pipeline. Best default: `coding_rules`."
          default: coding_rules
        node_type:
          anyOf:
            - type: string
            - type: "null"
          title: Node Type
          description: "Optional node type filter. Best default: omit."
          examples:
            - document
        node_names:
          items:
            type: string
          type: array
          title: Node Names
          description: "Optional node-name filter. Best default: empty list."
          examples:
            - - Cortex API Overview
        session_ids:
          items:
            type: string
          type: array
          title: Session Ids
          description: "Optional session filters for session-aware pipelines. Best
            default: empty list."
          examples:
            - - session_demo_001
        custom_extraction_profile:
          anyOf:
            - type: string
            - type: "null"
          title: Custom Extraction Profile
          description: "Optional custom extraction profile for `pipeline=custom`. Best
            default: omit."
          examples:
            - custom/memify/extract-v1
        custom_enrichment_profile:
          anyOf:
            - type: string
            - type: "null"
          title: Custom Enrichment Profile
          description: "Optional custom enrichment profile for `pipeline=custom`. Best
            default: omit."
          examples:
            - custom/memify/enrich-v1
        webhook:
          anyOf:
            - $ref: "#/components/schemas/WebhookConfig"
            - type: "null"
          description: "Optional webhook callback. Best default: omit."
      type: object
      title: MemifyJobRequest
    MemifyPipeline:
      type: string
      enum:
        - coding_rules
        - triplet_embeddings
        - session_persistence
        - entity_consolidation
        - custom
      title: MemifyPipeline
    MultipartPartUpload:
      properties:
        part_number:
          type: integer
          minimum: 1
          title: Part Number
        method:
          type: string
          title: Method
        url:
          type: string
          title: Url
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
      type: object
      required:
        - part_number
        - method
        - url
      title: MultipartPartUpload
    ParseArtifacts:
      properties:
        markdown_object:
          anyOf:
            - $ref: "#/components/schemas/StorageObjectRef"
            - type: "null"
        raw_html_object:
          anyOf:
            - $ref: "#/components/schemas/StorageObjectRef"
            - type: "null"
        screenshot_object:
          anyOf:
            - $ref: "#/components/schemas/StorageObjectRef"
            - type: "null"
        pdf_object:
          anyOf:
            - $ref: "#/components/schemas/StorageObjectRef"
            - type: "null"
        ssl_certificate:
          anyOf:
            - $ref: "#/components/schemas/SslCertificateSummary"
            - type: "null"
      type: object
      title: ParseArtifacts
    ParseAttemptStatus:
      type: string
      enum:
        - succeeded
        - failed
        - skipped
      title: ParseAttemptStatus
    ParseBatchJobAccepted:
      properties:
        requested_sources:
          items:
            type: string
          type: array
          title: Requested Sources
        engine_id:
          type: string
          title: Engine Id
        scene:
          anyOf:
            - type: string
            - type: "null"
          title: Scene
        jobs:
          items:
            $ref: "#/components/schemas/JobAccepted"
          type: array
          title: Jobs
      type: object
      required:
        - engine_id
      title: ParseBatchJobAccepted
    ParseBatchResult:
      properties:
        requested_sources:
          items:
            type: string
          type: array
          title: Requested Sources
        engine_id:
          type: string
          title: Engine Id
        scene:
          anyOf:
            - type: string
            - type: "null"
          title: Scene
        results:
          items:
            $ref: "#/components/schemas/ParseResult"
          type: array
          title: Results
      type: object
      required:
        - engine_id
      title: ParseBatchResult
    ParseDiagnostics:
      properties:
        selected_engine_key:
          anyOf:
            - type: string
            - type: "null"
          title: Selected Engine Key
        fallback_used:
          type: boolean
          title: Fallback Used
          default: false
        engine_attempts:
          items:
            $ref: "#/components/schemas/ParseEngineAttempt"
          type: array
          title: Engine Attempts
        warnings:
          items:
            type: string
          type: array
          title: Warnings
        link_counts:
          additionalProperties:
            type: integer
          type: object
          title: Link Counts
        media_counts:
          additionalProperties:
            type: integer
          type: object
          title: Media Counts
        anti_bot_strategy:
          anyOf:
            - type: string
            - type: "null"
          title: Anti Bot Strategy
        used_proxy:
          anyOf:
            - type: boolean
            - type: "null"
          title: Used Proxy
        timings_ms:
          $ref: "#/components/schemas/ParseTimingSummary"
        telemetry:
          anyOf:
            - $ref: "#/components/schemas/TelemetryContext"
            - type: "null"
      type: object
      title: ParseDiagnostics
    ParseEngineAttempt:
      properties:
        attempt_no:
          type: integer
          minimum: 1
          title: Attempt No
        engine_key:
          type: string
          title: Engine Key
        status:
          $ref: "#/components/schemas/ParseAttemptStatus"
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Started At
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Completed At
        error_code:
          anyOf:
            - type: string
            - type: "null"
          title: Error Code
        warning:
          anyOf:
            - type: string
            - type: "null"
          title: Warning
        diagnostics:
          additionalProperties: true
          type: object
          title: Diagnostics
      type: object
      required:
        - attempt_no
        - engine_key
        - status
      title: ParseEngineAttempt
    ParseEngineDeploymentMode:
      type: string
      enum:
        - local
        - remote
        - hybrid
      title: ParseEngineDeploymentMode
    ParseEngineDescriptor:
      properties:
        engine_key:
          type: string
          title: Engine Key
        display_name:
          type: string
          title: Display Name
        engine_family:
          type: string
          title: Engine Family
        deployment_mode:
          $ref: "#/components/schemas/ParseEngineDeploymentMode"
        status:
          $ref: "#/components/schemas/ParseEngineStatus"
        supported_source_types:
          items:
            type: string
          type: array
          title: Supported Source Types
        supported_formats:
          items:
            type: string
          type: array
          title: Supported Formats
        capabilities:
          items:
            type: string
          type: array
          title: Capabilities
        default_scene_id:
          anyOf:
            - type: string
            - type: "null"
          title: Default Scene Id
        supported_scene_ids:
          items:
            type: string
          type: array
          title: Supported Scene Ids
        default_profile_ref:
          anyOf:
            - type: string
            - type: "null"
          title: Default Profile Ref
      type: object
      required:
        - engine_key
        - display_name
        - engine_family
        - deployment_mode
        - status
      title: ParseEngineDescriptor
    ParseEngineList:
      properties:
        engines:
          items:
            $ref: "#/components/schemas/ParseEngineDescriptor"
          type: array
          title: Engines
      type: object
      title: ParseEngineList
    ParseEngineStatus:
      type: string
      enum:
        - active
        - disabled
        - deprecated
      title: ParseEngineStatus
    ParseInputKind:
      type: string
      enum:
        - url
        - object
        - uri
      title: ParseInputKind
    ParseJobSubmitRequest:
      properties:
        sources:
          items:
            type: string
          type: array
          minItems: 1
          title: Sources
          description: Required source locators. Each item may be an HTTP(S) URL, `s3://`
            URI, `file://` URI, raw Cortex storage object key such as
            `cortex-local/tenant_demo/obj_.../file.pdf`, or
            `cortex://objects/{object_id}` reference. For Cortex-managed
            S3/MinIO keys, Cortex extracts the `obj_...` segment and resolves a
            signed download URL automatically.
          examples:
            - - https://docs.cognee.ai/core-concepts/overview
              - s3://cortex-local/tenant_demo/obj_a3da967e3ca446cab3631bb7/bofa_note.pdf
        engine_id:
          type: string
          minLength: 1
          title: Engine Id
          description: Public parser engine identifier. Use `auto` to let Cortex choose
            the best active engine and scene per source; otherwise use
            `crawl4ai`, `jina_reader`, `llama_parse`, `markitdown`, or
            `docling`.
          default: auto
          examples:
            - auto
        scene:
          anyOf:
            - type: string
            - type: "null"
          title: Scene
          description: "Optional high-level parse scene. Best default: omit to let Cortex
            select the engine's default scene. Typical values include
            `balanced`, `deep_web`, `authenticated_web`, `fast_extract`,
            `document_fidelity`, `document_ai`, or `lightweight`."
          examples:
            - deep_web
        priority:
          type: integer
          maximum: 10
          minimum: 1
          title: Priority
          description: "Job priority where higher values are more urgent. Best default: 5."
          default: 5
          examples:
            - 5
        webhook:
          anyOf:
            - $ref: "#/components/schemas/WebhookConfig"
            - type: "null"
          description: "Optional webhook callback configuration. Best default: omit."
      type: object
      required:
        - sources
      title: ParseJobSubmitRequest
    ParseNormalizationOptions:
      properties:
        schema_version:
          type: string
          title: Schema Version
          description: "Normalization schema version. Best default: `cortex.parse.v1`."
          default: cortex.parse.v1
        normalize_markdown:
          type: boolean
          title: Normalize Markdown
          description: "Normalize headings, lists, whitespace, and block structure. Best
            default: `true`."
          default: true
        normalize_metadata:
          type: boolean
          title: Normalize Metadata
          description: "Normalize metadata into Cortex's standard document metadata shape.
            Best default: `true`."
          default: true
        metadata_schema_ref:
          anyOf:
            - type: string
            - type: "null"
          title: Metadata Schema Ref
          description: "Optional metadata schema profile reference. Best default: omit."
          examples:
            - metadata/default-web-page
        infer_title:
          type: boolean
          title: Infer Title
          description: "Infer a title when the source does not provide one cleanly. Best
            default: `true`."
          default: true
        infer_language:
          type: boolean
          title: Infer Language
          description: "Infer language when it is missing from the source. Best default:
            `true`."
          default: true
        include_page_metadata:
          type: boolean
          title: Include Page Metadata
          description: "Include page-level metadata such as URL, status, and fetch
            diagnostics. Best default: `true`."
          default: true
        preserve_source_blocks:
          type: boolean
          title: Preserve Source Blocks
          description: "Preserve raw source fragments in normalized output. Best default:
            `false`."
          default: false
        deduplicate_whitespace:
          type: boolean
          title: Deduplicate Whitespace
          description: "Collapse redundant whitespace during normalization. Best default:
            `true`."
          default: true
      type: object
      title: ParseNormalizationOptions
    ParseResult:
      properties:
        job_id:
          anyOf:
            - type: string
            - type: "null"
          title: Job Id
        document:
          $ref: "#/components/schemas/ParsedDocument"
        artifacts:
          anyOf:
            - $ref: "#/components/schemas/ParseArtifacts"
            - type: "null"
        diagnostics:
          $ref: "#/components/schemas/ParseDiagnostics"
        telemetry:
          anyOf:
            - $ref: "#/components/schemas/TelemetryContext"
            - type: "null"
      type: object
      required:
        - document
        - diagnostics
      title: ParseResult
    ParseSubmitRequest:
      properties:
        sources:
          items:
            type: string
          type: array
          minItems: 1
          title: Sources
          description: Required source locators. Each item may be an HTTP(S) URL, `s3://`
            URI, `file://` URI, raw Cortex storage object key such as
            `cortex-local/tenant_demo/obj_.../file.pdf`, or
            `cortex://objects/{object_id}` reference. For Cortex-managed
            S3/MinIO keys, Cortex extracts the `obj_...` segment and resolves a
            signed download URL automatically.
          examples:
            - - https://docs.cognee.ai/core-concepts/overview
              - s3://cortex-local/tenant_demo/obj_a3da967e3ca446cab3631bb7/bofa_note.pdf
        engine_id:
          type: string
          minLength: 1
          title: Engine Id
          description: Public parser engine identifier. Use `auto` to let Cortex choose
            the best active engine and scene per source; otherwise use
            `crawl4ai`, `jina_reader`, `llama_parse`, `markitdown`, or
            `docling`.
          default: auto
          examples:
            - auto
        scene:
          anyOf:
            - type: string
            - type: "null"
          title: Scene
          description: "Optional high-level parse scene. Best default: omit to let Cortex
            select the engine's default scene. Typical values include
            `balanced`, `deep_web`, `authenticated_web`, `fast_extract`,
            `document_fidelity`, `document_ai`, or `lightweight`."
          examples:
            - deep_web
      type: object
      required:
        - sources
      title: ParseSubmitRequest
    ParseTimingSummary:
      properties:
        fetch:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Fetch
        render:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Render
        normalize:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Normalize
        total:
          type: integer
          minimum: 0
          title: Total
          default: 0
      type: object
      title: ParseTimingSummary
    ParsedDocument:
      properties:
        document_id:
          type: string
          title: Document Id
        source_type:
          $ref: "#/components/schemas/ParseInputKind"
        source_format:
          type: string
          title: Source Format
        markdown:
          type: string
          title: Markdown
        audit:
          $ref: "#/components/schemas/AuditFields"
        source_url:
          anyOf:
            - type: string
            - type: "null"
          title: Source Url
        source_object_id:
          anyOf:
            - type: string
            - type: "null"
          title: Source Object Id
        source_uri:
          anyOf:
            - type: string
            - type: "null"
          title: Source Uri
        canonical_url:
          anyOf:
            - type: string
            - type: "null"
          title: Canonical Url
        title:
          anyOf:
            - type: string
            - type: "null"
          title: Title
        language_code:
          anyOf:
            - type: string
            - type: "null"
          title: Language Code
        detected_mime_type:
          anyOf:
            - type: string
            - type: "null"
          title: Detected Mime Type
        category_tags:
          items:
            type: string
          type: array
          title: Category Tags
        labels:
          items:
            type: string
          type: array
          title: Labels
        access_policy:
          anyOf:
            - $ref: "#/components/schemas/AccessPolicy"
            - type: "null"
        markdown_sha256:
          anyOf:
            - type: string
              pattern: ^[0-9a-f]{64}$
            - type: "null"
          title: Markdown Sha256
        normalized_metadata:
          $ref: "#/components/schemas/StandardMetadata"
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        parser:
          $ref: "#/components/schemas/AppliedParseEngine"
        provenance:
          $ref: "#/components/schemas/DocumentProvenance"
      type: object
      required:
        - document_id
        - source_type
        - source_format
        - markdown
        - audit
      title: ParsedDocument
    ParserProfile:
      properties:
        profile_ref:
          type: string
          title: Profile Ref
        display_name:
          type: string
          title: Display Name
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        routing_mode:
          anyOf:
            - type: string
            - type: "null"
          title: Routing Mode
        preferred_engine_key:
          anyOf:
            - type: string
            - type: "null"
          title: Preferred Engine Key
        allowed_engines:
          items:
            type: string
          type: array
          title: Allowed Engines
        normalization_defaults:
          $ref: "#/components/schemas/ParseNormalizationOptions"
        fallback_policy:
          $ref: "#/components/schemas/FallbackPolicy"
      type: object
      required:
        - profile_ref
        - display_name
      title: ParserProfile
    ParserProfileList:
      properties:
        profiles:
          items:
            $ref: "#/components/schemas/ParserProfile"
          type: array
          title: Profiles
      type: object
      title: ParserProfileList
    PresignedRequestDescriptor:
      properties:
        method:
          type: string
          title: Method
        url:
          type: string
          title: Url
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
      type: object
      required:
        - method
        - url
      title: PresignedRequestDescriptor
    SearchFilters:
      properties:
        document_ids:
          items:
            type: string
          type: array
          title: Document Ids
          description: "Optional document allow-list. Best default: empty list."
          examples:
            - - doc_71fe50adf1cb4981bb322f0d74f32598
        object_ids:
          items:
            type: string
          type: array
          title: Object Ids
          description: "Optional object allow-list. Best default: empty list."
          examples:
            - - obj_3f6c1d5e9b1646b5a4eabdbf8b417bd3
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: "Optional tag filter. Best default: empty list."
          examples:
            - - docs
        node_sets:
          items:
            type: string
          type: array
          title: Node Sets
          description: "Optional node-set filter. Best default: empty list."
          examples:
            - - docs
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: "Optional exact-match metadata filters. Best default: empty object."
          examples:
            - domain: product
      type: object
      title: SearchFilters
    SearchHit:
      properties:
        rank:
          type: integer
          minimum: 1
          title: Rank
        hit_type:
          $ref: "#/components/schemas/SearchHitType"
        score:
          type: number
          title: Score
        source_id:
          anyOf:
            - type: string
            - type: "null"
          title: Source Id
        document_id:
          anyOf:
            - type: string
            - type: "null"
          title: Document Id
        object_id:
          anyOf:
            - type: string
            - type: "null"
          title: Object Id
        title:
          anyOf:
            - type: string
            - type: "null"
          title: Title
        snippet:
          anyOf:
            - type: string
            - type: "null"
          title: Snippet
        citation:
          anyOf:
            - $ref: "#/components/schemas/Citation"
            - type: "null"
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      type: object
      required:
        - rank
        - hit_type
        - score
      title: SearchHit
    SearchHitType:
      type: string
      enum:
        - chunk
        - summary
        - graph_node
        - graph_edge
        - triplet
        - rule
        - cypher_row
      title: SearchHitType
    SearchRequest:
      properties:
        query_text:
          type: string
          title: Query Text
          description: Required natural-language query or search expression.
          examples:
            - What does the documentation say about Cortex parse workflows?
        dataset_ids:
          items:
            type: string
          type: array
          title: Dataset Ids
          description: "Optional dataset ID scope. Best default: empty list."
          examples:
            - - dset_9558cfc9178444e4a4c60d5658db78f5
        dataset_keys:
          items:
            type: string
          type: array
          title: Dataset Keys
          description: "Optional dataset key scope. Recommended for human-authored
            requests. Best default: empty list."
          examples:
            - - product_docs
        search_type:
          $ref: "#/components/schemas/SearchType"
          description: "Search strategy. Best default: `GRAPH_COMPLETION`."
          default: GRAPH_COMPLETION
        top_k:
          type: integer
          maximum: 100
          minimum: 1
          title: Top K
          description: "Maximum number of context hits to return. Best default: 10."
          default: 10
          examples:
            - 10
        session_id:
          anyOf:
            - type: string
            - type: "null"
          title: Session Id
          description: "Optional session scope for session-aware search. Best default:
            omit."
          examples:
            - session_demo_001
        filters:
          $ref: "#/components/schemas/SearchFilters"
          description: "Optional structured filters. Best default: empty filters."
        only_context:
          type: boolean
          title: Only Context
          description: "Return context hits without an answer synthesis. Best default:
            `false`."
          default: false
        include_provenance:
          type: boolean
          title: Include Provenance
          description: "Include citation/provenance metadata in hits. Best default: `true`."
          default: true
        include_graph_paths:
          type: boolean
          title: Include Graph Paths
          description: "Include graph path explanations when supported. Best default:
            `false`."
          default: false
        timeout_seconds:
          type: integer
          maximum: 300
          minimum: 1
          title: Timeout Seconds
          description: "Search timeout in seconds. Best default: 30."
          default: 30
          examples:
            - 30
      type: object
      required:
        - query_text
      title: SearchRequest
    SearchResponse:
      properties:
        request_id:
          type: string
          title: Request Id
        search_type:
          $ref: "#/components/schemas/SearchType"
        context_items:
          items:
            $ref: "#/components/schemas/SearchHit"
          type: array
          title: Context Items
        latency_ms:
          type: integer
          minimum: 0
          title: Latency Ms
        created_at:
          type: string
          format: date-time
          title: Created At
        dataset_scope:
          items:
            type: string
          type: array
          title: Dataset Scope
        answer:
          anyOf:
            - type: string
            - type: "null"
          title: Answer
        graph_paths:
          items:
            $ref: "#/components/schemas/GraphPath"
          type: array
          title: Graph Paths
        telemetry:
          anyOf:
            - $ref: "#/components/schemas/TelemetryContext"
            - type: "null"
      type: object
      required:
        - request_id
        - search_type
        - context_items
        - latency_ms
        - created_at
      title: SearchResponse
    SearchType:
      type: string
      enum:
        - GRAPH_COMPLETION
        - RAG_COMPLETION
        - CHUNKS
        - SUMMARIES
        - GRAPH_SUMMARY_COMPLETION
        - GRAPH_COMPLETION_COT
        - GRAPH_COMPLETION_CONTEXT_EXTENSION
        - TRIPLET_COMPLETION
        - CHUNKS_LEXICAL
        - CODING_RULES
        - TEMPORAL
        - CYPHER
        - NATURAL_LANGUAGE
      title: SearchType
    SslCertificateSummary:
      properties:
        issuer_common_name:
          anyOf:
            - type: string
            - type: "null"
          title: Issuer Common Name
        valid_from:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Valid From
        valid_until:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Valid Until
        fingerprint:
          anyOf:
            - type: string
            - type: "null"
          title: Fingerprint
      type: object
      title: SslCertificateSummary
    StandardMetadata:
      properties:
        title:
          anyOf:
            - type: string
            - type: "null"
          title: Title
        author:
          anyOf:
            - type: string
            - type: "null"
          title: Author
        publish_date:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Publish Date
        language:
          anyOf:
            - type: string
            - type: "null"
          title: Language
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        summary:
          anyOf:
            - type: string
            - type: "null"
          title: Summary
        keywords:
          items:
            type: string
          type: array
          title: Keywords
        category_tags:
          items:
            type: string
          type: array
          title: Category Tags
      type: object
      title: StandardMetadata
    StorageObject:
      properties:
        object_id:
          type: string
          title: Object Id
        filename:
          type: string
          title: Filename
        content_type:
          type: string
          title: Content Type
        size_bytes:
          type: integer
          minimum: 0
          title: Size Bytes
        status:
          $ref: "#/components/schemas/StorageObjectStatus"
        audit:
          $ref: "#/components/schemas/AuditFields"
        current_version_id:
          anyOf:
            - type: string
            - type: "null"
          title: Current Version Id
        bucket:
          anyOf:
            - type: string
            - type: "null"
          title: Bucket
        object_key:
          anyOf:
            - type: string
            - type: "null"
          title: Object Key
        checksum_sha256:
          anyOf:
            - type: string
              pattern: ^[0-9a-f]{64}$
            - type: "null"
          title: Checksum Sha256
        etag:
          anyOf:
            - type: string
            - type: "null"
          title: Etag
        storage_class:
          anyOf:
            - type: string
            - type: "null"
          title: Storage Class
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
        tags:
          items:
            type: string
          type: array
          title: Tags
        version:
          anyOf:
            - $ref: "#/components/schemas/StorageObjectVersion"
            - type: "null"
        access_policy:
          anyOf:
            - $ref: "#/components/schemas/AccessPolicy"
            - type: "null"
      type: object
      required:
        - object_id
        - filename
        - content_type
        - size_bytes
        - status
        - audit
      title: StorageObject
    StorageObjectRef:
      properties:
        object_id:
          type: string
          title: Object Id
        version_id:
          anyOf:
            - type: string
            - type: "null"
          title: Version Id
        bucket:
          anyOf:
            - type: string
            - type: "null"
          title: Bucket
        object_key:
          type: string
          title: Object Key
      type: object
      required:
        - object_id
        - object_key
      title: StorageObjectRef
    StorageObjectStatus:
      type: string
      enum:
        - available
        - archived
        - deleted
      title: StorageObjectStatus
    StorageObjectVersion:
      properties:
        object_version_id:
          type: string
          title: Object Version Id
        version_no:
          type: integer
          minimum: 1
          title: Version No
        size_bytes:
          type: integer
          minimum: 0
          title: Size Bytes
        provider_version_ref:
          anyOf:
            - type: string
            - type: "null"
          title: Provider Version Ref
        checksum_sha256:
          anyOf:
            - type: string
              pattern: ^[0-9a-f]{64}$
            - type: "null"
          title: Checksum Sha256
        etag:
          anyOf:
            - type: string
            - type: "null"
          title: Etag
        is_latest:
          type: boolean
          title: Is Latest
          default: true
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Created At
      type: object
      required:
        - object_version_id
        - version_no
        - size_bytes
      title: StorageObjectVersion
    StorageUploadCompleteRequest:
      properties:
        parts:
          items:
            $ref: "#/components/schemas/CompletedUploadPart"
          type: array
          title: Parts
          description: "Multipart parts to finalize. Best default: empty list for
            single-part uploads."
          examples:
            - - etag: '"part-1-etag"'
                part_number: 1
        checksum_sha256:
          anyOf:
            - type: string
              pattern: ^[0-9a-f]{64}$
            - type: "null"
          title: Checksum Sha256
          description: "Optional final SHA-256 checksum. Best default: omit unless the
            client validated the file digest."
          examples:
            - bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
      type: object
      title: StorageUploadCompleteRequest
    StorageUploadCreateRequest:
      properties:
        filename:
          type: string
          title: Filename
          description: Required original filename presented to storage and downstream
            parsers.
          examples:
            - product-overview.md
        content_type:
          anyOf:
            - type: string
            - type: "null"
          title: Content Type
          description: "Optional MIME type of the uploaded object. Best default: omit and
            let Cortex infer it from `filename`, then reconcile it with the
            object store during completion."
          examples:
            - text/markdown
        size_bytes:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Size Bytes
          description: "Optional total size of the upload in bytes. Best default: omit
            when unknown before upload; provide it when the client already knows
            the file size so Cortex can choose single-part vs multipart more
            accurately."
          examples:
            - 20480
        checksum_sha256:
          anyOf:
            - type: string
              pattern: ^[0-9a-f]{64}$
            - type: "null"
          title: Checksum Sha256
          description: "Optional SHA-256 checksum for integrity verification. Best
            default: omit if the client cannot compute it."
          examples:
            - aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
          description: "Optional metadata stored alongside the object. Best default: empty
            object."
          examples:
            - document_type: guide
              source: swagger-demo
        access_policy:
          anyOf:
            - $ref: "#/components/schemas/AccessPolicy"
            - type: "null"
          description: "Optional access policy attached to the stored object. Best
            default: omit."
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: "Optional tags used for filtering or governance. Best default:
            empty list."
          examples:
            - - docs
              - product
      type: object
      required:
        - filename
      title: StorageUploadCreateRequest
    StorageUploadSession:
      properties:
        upload_id:
          type: string
          title: Upload Id
        object_id:
          type: string
          title: Object Id
        status:
          $ref: "#/components/schemas/UploadSessionStatus"
        upload_mode:
          $ref: "#/components/schemas/UploadMode"
        bucket:
          anyOf:
            - type: string
            - type: "null"
          title: Bucket
        object_key:
          anyOf:
            - type: string
            - type: "null"
          title: Object Key
        expires_at:
          type: string
          format: date-time
          title: Expires At
        part_size_bytes:
          anyOf:
            - type: integer
            - type: "null"
          title: Part Size Bytes
        single_part:
          anyOf:
            - $ref: "#/components/schemas/PresignedRequestDescriptor"
            - type: "null"
        multipart_parts:
          items:
            $ref: "#/components/schemas/MultipartPartUpload"
          type: array
          title: Multipart Parts
      type: object
      required:
        - upload_id
        - object_id
        - status
        - upload_mode
        - expires_at
      title: StorageUploadSession
    StoredArtifactRef:
      properties:
        object_id:
          type: string
          title: Object Id
        label:
          type: string
          title: Label
        content_type:
          anyOf:
            - type: string
            - type: "null"
          title: Content Type
        format:
          anyOf:
            - type: string
            - type: "null"
          title: Format
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
      type: object
      required:
        - object_id
        - label
      title: StoredArtifactRef
    SynthesisConfig:
      properties:
        sample_count:
          anyOf:
            - type: integer
              minimum: 1
            - type: "null"
          title: Sample Count
        anonymize_pii:
          type: boolean
          title: Anonymize Pii
          default: false
        include_expected_output:
          anyOf:
            - type: boolean
            - type: "null"
          title: Include Expected Output
        max_contexts_per_case:
          anyOf:
            - type: integer
              minimum: 1
            - type: "null"
          title: Max Contexts Per Case
        quality_gates:
          items:
            $ref: "#/components/schemas/SynthesisQualityGate"
          type: array
          title: Quality Gates
        options:
          additionalProperties: true
          type: object
          title: Options
      type: object
      title: SynthesisConfig
    SynthesisEngineDescriptor:
      properties:
        engine_id:
          type: string
          title: Engine Id
        display_name:
          type: string
          title: Display Name
        availability_status:
          type: string
          pattern: ^(available|degraded|disabled)$
          title: Availability Status
        provider:
          anyOf:
            - type: string
            - type: "null"
          title: Provider
        supported_synthesis_types:
          items:
            $ref: "#/components/schemas/SynthesisType"
          type: array
          title: Supported Synthesis Types
        supported_source_types:
          items:
            type: string
          type: array
          title: Supported Source Types
        output_formats:
          items:
            type: string
          type: array
          title: Output Formats
        default_profiles:
          items:
            type: string
          type: array
          title: Default Profiles
        notes:
          anyOf:
            - type: string
            - type: "null"
          title: Notes
      type: object
      required:
        - engine_id
        - display_name
        - availability_status
      title: SynthesisEngineDescriptor
    SynthesisEngineList:
      properties:
        generated_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Generated At
        engines:
          items:
            $ref: "#/components/schemas/SynthesisEngineDescriptor"
          type: array
          title: Engines
      type: object
      required:
        - engines
      title: SynthesisEngineList
    SynthesisJobAccepted:
      properties:
        job_id:
          type: string
          title: Job Id
        job_type:
          $ref: "#/components/schemas/JobType"
        status:
          $ref: "#/components/schemas/JobStatus"
        submitted_at:
          type: string
          format: date-time
          title: Submitted At
        poll_url:
          type: string
          title: Poll Url
        result_url:
          anyOf:
            - type: string
            - type: "null"
          title: Result Url
        cancel_url:
          anyOf:
            - type: string
            - type: "null"
          title: Cancel Url
        telemetry:
          anyOf:
            - $ref: "#/components/schemas/TelemetryContext"
            - type: "null"
        synthesis_type:
          anyOf:
            - $ref: "#/components/schemas/SynthesisType"
            - type: "null"
        engine_id:
          anyOf:
            - type: string
            - type: "null"
          title: Engine Id
      type: object
      required:
        - job_id
        - job_type
        - status
        - submitted_at
        - poll_url
      title: SynthesisJobAccepted
    SynthesisJobSubmitRequest:
      properties:
        synthesis_type:
          $ref: "#/components/schemas/SynthesisType"
        source:
          $ref: "#/components/schemas/SynthesisSource"
        name:
          anyOf:
            - type: string
            - type: "null"
          title: Name
        engine_id:
          type: string
          title: Engine Id
          default: auto
        profile_key:
          anyOf:
            - type: string
            - type: "null"
          title: Profile Key
        config:
          $ref: "#/components/schemas/SynthesisConfig"
        output:
          $ref: "#/components/schemas/SynthesisOutputOptions"
        webhook:
          anyOf:
            - $ref: "#/components/schemas/WebhookConfig"
            - type: "null"
      type: object
      required:
        - synthesis_type
        - source
      title: SynthesisJobSubmitRequest
    SynthesisOutputOptions:
      properties:
        output_format:
          anyOf:
            - type: string
            - type: "null"
          title: Output Format
        persist_object_filename:
          anyOf:
            - type: string
            - type: "null"
          title: Persist Object Filename
        persist_dataset_key:
          anyOf:
            - type: string
            - type: "null"
          title: Persist Dataset Key
        include_preview:
          type: boolean
          title: Include Preview
          default: true
      type: object
      title: SynthesisOutputOptions
    SynthesisQualityGate:
      properties:
        metric_key:
          type: string
          title: Metric Key
        threshold:
          anyOf:
            - type: number
            - type: "null"
          title: Threshold
        params:
          additionalProperties: true
          type: object
          title: Params
      type: object
      required:
        - metric_key
      title: SynthesisQualityGate
    SynthesisQualityResult:
      properties:
        metric_key:
          type: string
          title: Metric Key
        status:
          type: string
          pattern: ^(passed|failed|warn|info)$
          title: Status
        threshold:
          anyOf:
            - type: number
            - type: "null"
          title: Threshold
        score:
          anyOf:
            - type: number
            - type: "null"
          title: Score
        unit:
          anyOf:
            - type: string
            - type: "null"
          title: Unit
        details:
          additionalProperties: true
          type: object
          title: Details
      type: object
      required:
        - metric_key
        - status
      title: SynthesisQualityResult
    SynthesisRunResult:
      properties:
        synthesis_type:
          $ref: "#/components/schemas/SynthesisType"
        engine_id:
          type: string
          title: Engine Id
        status:
          type: string
          pattern: ^(succeeded|failed|partial)$
          title: Status
        synthesis_run_id:
          anyOf:
            - type: string
            - type: "null"
          title: Synthesis Run Id
        job_id:
          anyOf:
            - type: string
            - type: "null"
          title: Job Id
        name:
          anyOf:
            - type: string
            - type: "null"
          title: Name
        profile_key:
          anyOf:
            - type: string
            - type: "null"
          title: Profile Key
        source_summary:
          additionalProperties: true
          type: object
          title: Source Summary
        summary:
          $ref: "#/components/schemas/SynthesisSummary"
        quality_gates:
          items:
            $ref: "#/components/schemas/SynthesisQualityResult"
          type: array
          title: Quality Gates
        outputs:
          items:
            $ref: "#/components/schemas/StoredArtifactRef"
          type: array
          title: Outputs
        output_dataset_id:
          anyOf:
            - type: string
            - type: "null"
          title: Output Dataset Id
        telemetry:
          anyOf:
            - $ref: "#/components/schemas/TelemetryContext"
            - type: "null"
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Started At
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Completed At
      type: object
      required:
        - synthesis_type
        - engine_id
        - status
      title: SynthesisRunResult
    SynthesisSource:
      properties:
        type:
          type: string
          title: Type
        dataset_id:
          anyOf:
            - type: string
            - type: "null"
          title: Dataset Id
        object_id:
          anyOf:
            - type: string
            - type: "null"
          title: Object Id
        object_ids:
          items:
            type: string
          type: array
          title: Object Ids
        metadata_object_id:
          anyOf:
            - type: string
            - type: "null"
          title: Metadata Object Id
        inline_records:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Inline Records
        documents:
          items:
            type: string
          type: array
          title: Documents
        field_mapping:
          additionalProperties:
            type: string
          type: object
          title: Field Mapping
        options:
          additionalProperties: true
          type: object
          title: Options
      type: object
      required:
        - type
      title: SynthesisSource
    SynthesisSummary:
      properties:
        requested_sample_count:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Requested Sample Count
        output_sample_count:
          anyOf:
            - type: integer
              minimum: 0
            - type: "null"
          title: Output Sample Count
        quality_score:
          anyOf:
            - type: number
            - type: "null"
          title: Quality Score
        privacy_score:
          anyOf:
            - type: number
            - type: "null"
          title: Privacy Score
        notes:
          items:
            type: string
          type: array
          title: Notes
      type: object
      title: SynthesisSummary
    SynthesisSyncRequest:
      properties:
        synthesis_type:
          $ref: "#/components/schemas/SynthesisType"
        source:
          $ref: "#/components/schemas/SynthesisSource"
        name:
          anyOf:
            - type: string
            - type: "null"
          title: Name
        engine_id:
          type: string
          title: Engine Id
          default: auto
        profile_key:
          anyOf:
            - type: string
            - type: "null"
          title: Profile Key
        config:
          $ref: "#/components/schemas/SynthesisConfig"
        output:
          $ref: "#/components/schemas/SynthesisOutputOptions"
        webhook:
          anyOf:
            - $ref: "#/components/schemas/WebhookConfig"
            - type: "null"
      type: object
      required:
        - synthesis_type
        - source
      title: SynthesisSyncRequest
    SynthesisType:
      type: string
      enum:
        - structured_single_table
        - structured_relational
        - rag_goldens
        - qa_pairs
        - conversation_goldens
        - agent_trajectories
        - custom
      title: SynthesisType
    TelemetryContext:
      properties:
        trace_id:
          anyOf:
            - type: string
            - type: "null"
          title: Trace Id
        span_id:
          anyOf:
            - type: string
            - type: "null"
          title: Span Id
        request_id:
          anyOf:
            - type: string
            - type: "null"
          title: Request Id
        deployment_ring:
          anyOf:
            - type: string
            - type: "null"
          title: Deployment Ring
        experiment_variant:
          anyOf:
            - type: string
            - type: "null"
          title: Experiment Variant
      type: object
      title: TelemetryContext
    UploadMode:
      type: string
      enum:
        - single_part
        - multipart
      title: UploadMode
    UploadSessionStatus:
      type: string
      enum:
        - pending_upload
      title: UploadSessionStatus
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    WebhookConfig:
      properties:
        url:
          type: string
          title: Url
          description: Required callback URL invoked on job lifecycle events.
          examples:
            - https://example.com/hooks/cortex/parse
        secret_ref:
          anyOf:
            - type: string
            - type: "null"
          title: Secret Ref
          description: "Optional secret reference used to sign or authenticate webhook
            delivery. Best default: omit."
          examples:
            - vault:cortex/webhooks/parse
        event_types:
          items:
            type: string
          type: array
          title: Event Types
          description: "Optional event types to send. Best default: empty list, which
            means the service default set."
          examples:
            - - job.succeeded
              - job.failed
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
          description: "Optional static headers sent with the webhook. Best default: empty
            object."
          examples:
            - X-Consumer: knowledge-pipeline
      type: object
      required:
        - url
      title: WebhookConfig
  securitySchemes:
    BearerAuth:
      type: http
      description: Bearer access token for protected Cortex APIs.
      scheme: bearer