openapi: 3.1.0
info:
  title: Nia AI API
  version: 1.1.0
  description: Nia API contract used to generate official Python and TypeScript SDKs.
paths:
  /account/export:
    post:
      tags:
        - v2-api
        - v2-api
      summary: Export Account
      operationId: export_account_v2_account_export_post
      parameters:
        - name: Authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /account/import:
    post:
      tags:
        - v2-api
        - v2-api
      summary: Import Account
      operationId: import_account_v2_account_import_post
      parameters:
        - name: Authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /advisor:
    post:
      tags:
        - v2-api
        - advisor
      summary: Context-aware code advisor
      description: >-
        Analyze codebase context against Nia's indexed documentation to get
        tailored recommendations.
      operationId: analyze_codebase_v2_advisor_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdvisorRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvisorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/bootstrap-key:
    post:
      tags:
        - v2-api
        - auth-bootstrap
      summary: Bootstrap Key
      description: >-
        **Deprecated** — Use POST /v2/auth/signup (returns key directly) + POST
        /v2/auth/verify instead.


        Exchange a bootstrap token for an nk_ API key (one-time use).
      operationId: bootstrap_key_v2_auth_bootstrap_key_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BootstrapKeyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BootstrapKeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
  /auth/login:
    post:
      tags:
        - v2-api
        - auth-bootstrap
      summary: Login
      description: |-
        Request a verification code for passwordless login.

        A 6-digit code is sent to the provided email. Exchange it via
        POST /v2/auth/login/verify to receive a new API key.
      operationId: login_v2_auth_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/login-key:
    post:
      tags:
        - v2-api
        - auth-bootstrap
      summary: Login Key
      description: >-
        **Deprecated** — Use POST /v2/auth/login + POST /v2/auth/login/verify
        instead.


        Authenticate with email + password and receive a new nk_ API key.
      operationId: login_key_v2_auth_login_key_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginKeyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginKeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
  /auth/login/verify:
    post:
      tags:
        - v2-api
        - auth-bootstrap
      summary: Login Verify
      description: Verify login code and receive a new full-access API key.
      operationId: login_verify_v2_auth_login_verify_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginVerifyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginVerifyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/resend-code:
    post:
      tags:
        - v2-api
        - auth-bootstrap
      summary: Resend Code
      description: |-
        Resend the verification code for an unverified API key.

        Requires the read-only API key in the Authorization header.
      operationId: resend_code_v2_auth_resend_code_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResendCodeResponse'
  /auth/signup:
    post:
      tags:
        - v2-api
        - auth-bootstrap
      summary: Signup
      description: |-
        Create a new account and receive a read-only API key.

        A 6-digit verification code is sent to the provided email. Call
        POST /v2/auth/verify with the code (and this key in the Authorization
        header) to upgrade to full access.
      operationId: signup_v2_auth_signup_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/verify:
    post:
      tags:
        - v2-api
        - auth-bootstrap
      summary: Verify
      description: |-
        Verify your account using the 6-digit code sent to your email.

        On success, the API key used in the Authorization header is upgraded
        from read-only to full access.
      operationId: verify_v2_auth_verify_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /bulk-delete:
    post:
      tags:
        - v2-api
        - v2-api
      summary: Bulk delete resources
      description: >-
        Delete multiple resources in a single request. Supports repositories,
        documentation, research papers, contexts, and local folders.
      operationId: bulk_delete_resources_v2_bulk_delete_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkDeleteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /categories:
    get:
      tags:
        - v2-api
        - v2-api-categories
      summary: List categories
      description: List categories for the authenticated user/organization.
      operationId: list_categories_v2_categories_get
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            description: Number of categories to return
            default: 50
            title: Limit
          description: Number of categories to return
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            description: Number of categories to skip
            default: 0
            title: Offset
          description: Number of categories to skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryListCompatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
        - v2-api
        - v2-api-categories
      summary: Create category
      description: Create a new category for organizing data sources.
      operationId: create_category_v2_categories_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/routes__v2__categories__CategoryCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /categories/{category_id}:
    patch:
      tags:
        - v2-api
        - v2-api-categories
      summary: Update category
      description: Update an existing category.
      operationId: update_category_v2_categories__category_id__patch
      parameters:
        - name: category_id
          in: path
          required: true
          schema:
            type: string
            title: Category Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/routes__v2__categories__CategoryUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - v2-api
        - v2-api-categories
      summary: Delete category
      description: >-
        Delete a category. Data sources with this category will become
        uncategorized.
      operationId: delete_category_v2_categories__category_id__delete
      parameters:
        - name: category_id
          in: path
          required: true
          schema:
            type: string
            title: Category Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /connectors:
    get:
      tags:
        - v2-api
        - connectors
      summary: List Available Connectors
      description: List all available connector types with their metadata.
      operationId: list_available_connectors_v2_connectors_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /connectors/installations:
    get:
      tags:
        - v2-api
        - connectors
      summary: List Installations
      description: List all connector installations for the current user/org.
      operationId: list_installations_v2_connectors_installations_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /connectors/installations/{installation_id}:
    delete:
      tags:
        - v2-api
        - connectors
      summary: Delete Installation
      description: Disconnect a connector installation.
      operationId: delete_installation_v2_connectors_installations__installation_id__delete
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /connectors/installations/{installation_id}/index:
    post:
      tags:
        - v2-api
        - connectors
      summary: Index Installation
      description: Trigger indexing for a connector installation.
      operationId: >-
        index_installation_v2_connectors_installations__installation_id__index_post
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /connectors/installations/{installation_id}/schedule:
    patch:
      tags:
        - v2-api
        - connectors
      summary: Update Schedule
      description: Update sync schedule for a connector installation.
      operationId: >-
        update_schedule_v2_connectors_installations__installation_id__schedule_patch
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /connectors/installations/{installation_id}/status:
    get:
      tags:
        - v2-api
        - connectors
      summary: Get Installation Status
      description: Get sync status and health for a connector installation.
      operationId: >-
        get_installation_status_v2_connectors_installations__installation_id__status_get
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /connectors/{connector_type}/install:
    post:
      tags:
        - v2-api
        - connectors
      summary: Install Connector
      description: Install a connector — either store API key or initiate OAuth flow.
      operationId: install_connector_v2_connectors__connector_type__install_post
      parameters:
        - name: connector_type
          in: path
          required: true
          schema:
            type: string
            title: Connector Type
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /connectors/{connector_type}/oauth/callback:
    get:
      tags:
        - v2-api
        - connectors
      summary: Oauth Callback
      description: >-
        Handle OAuth callback — exchange code, create installation, redirect to
        frontend.
      operationId: oauth_callback_v2_connectors__connector_type__oauth_callback_get
      parameters:
        - name: connector_type
          in: path
          required: true
          schema:
            type: string
            title: Connector Type
        - name: code
          in: query
          required: true
          schema:
            type: string
            title: Code
        - name: state
          in: query
          required: true
          schema:
            type: string
            title: State
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /contexts:
    post:
      tags:
        - v2-api
        - v2-api-contexts
      summary: Save context
      description: >-
        Save conversation context for cross-agent sharing. Indexed in vector
        store for semantic search.
      operationId: save_context_v2_v2_contexts_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextShareRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextShareResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
        - v2-api
        - v2-api-contexts
      summary: List contexts
      description: >-
        List conversation contexts with pagination. Filter by tags, agent
        source, or memory type.
      operationId: list_contexts_v2_v2_contexts_get
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Number of contexts to return
            default: 20
            title: Limit
          description: Number of contexts to return
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            description: Number of contexts to skip
            default: 0
            title: Offset
          description: Number of contexts to skip
        - name: tags
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Comma-separated tags to filter by
            title: Tags
          description: Comma-separated tags to filter by
        - name: agent_source
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by agent source
            title: Agent Source
          description: Filter by agent source
        - name: memory_type
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: 'Filter by memory type: scratchpad, episodic, fact, procedural'
            title: Memory Type
          description: 'Filter by memory type: scratchpad, episodic, fact, procedural'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextListCompatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /contexts/search:
    get:
      tags:
        - v2-api
        - v2-api-contexts
      summary: Text search contexts
      description: >-
        Search contexts by content, title, summary, or tags using MongoDB text
        search.
      operationId: search_contexts_v2_v2_contexts_search_get
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            description: Search query
            title: Q
          description: Search query
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Number of contexts to return
            default: 20
            title: Limit
          description: Number of contexts to return
        - name: tags
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Comma-separated tags to filter by
            title: Tags
          description: Comma-separated tags to filter by
        - name: agent_source
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by agent source
            title: Agent Source
          description: Filter by agent source
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /contexts/semantic-search:
    get:
      tags:
        - v2-api
        - v2-api-contexts
      summary: Semantic search contexts
      description: >-
        Vector + BM25 hybrid search over contexts. Returns relevance scores and
        highlights.
      operationId: semantic_search_contexts_v2_v2_contexts_semantic_search_get
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            description: Search query
            title: Q
          description: Search query
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Number of contexts to return
            default: 20
            title: Limit
          description: Number of contexts to return
        - name: include_highlights
          in: query
          required: false
          schema:
            type: boolean
            description: Include match highlights
            default: true
            title: Include Highlights
          description: Include match highlights
        - name: workspace_filter
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by specific workspace name
            title: Workspace Filter
          description: Filter by specific workspace name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextSemanticSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /contexts/{context_id}:
    get:
      tags:
        - v2-api
        - v2-api-contexts
      summary: Get context
      description: Retrieve a specific context by ID.
      operationId: get_context_v2_v2_contexts__context_id__get
      parameters:
        - name: context_id
          in: path
          required: true
          schema:
            type: string
            title: Context Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextShareResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
        - v2-api
        - v2-api-contexts
      summary: Update context
      description: >-
        Update an existing context. Re-indexes in vector store if content
        changes.
      operationId: update_context_v2_v2_contexts__context_id__put
      parameters:
        - name: context_id
          in: path
          required: true
          schema:
            type: string
            title: Context Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextShareUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextShareResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - v2-api
        - v2-api-contexts
      summary: Delete context
      description: Soft delete a context (marks inactive).
      operationId: delete_context_v2_v2_contexts__context_id__delete
      parameters:
        - name: context_id
          in: path
          required: true
          schema:
            type: string
            title: Context Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /dependencies/analyze:
    post:
      tags:
        - v2-api
        - v2-api
      summary: Analyze package manifest
      description: >-
        Parse a package manifest and return dependency information with
        documentation URL mappings. This is a preview - no subscriptions are
        created.
      operationId: analyze_dependencies_v2_dependencies_analyze_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DependencyAnalyzeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /dependencies/subscribe:
    post:
      tags:
        - v2-api
        - v2-api
      summary: Subscribe to documentation for manifest dependencies
      description: >-
        Parse a package manifest and automatically subscribe to documentation
        for all dependencies.
      operationId: subscribe_to_dependencies_v2_dependencies_subscribe_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DependencySubscribeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/routes__v2__dependencies__SubscribeResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /dependencies/upload:
    post:
      tags:
        - v2-api
        - v2-api
      summary: Upload manifest file and subscribe to dependencies
      description: >-
        Upload a package manifest file and subscribe to documentation for all
        dependencies.
      operationId: upload_and_subscribe_v2_dependencies_upload_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/Body_upload_and_subscribe_v2_dependencies_upload_post
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/routes__v2__dependencies__SubscribeResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /document/agent:
    post:
      tags:
        - v2-api
        - document-agent
      summary: Query document(s) with an AI agent (synchronous)
      description: >-
        Run the full document agent against one or more indexed PDFs or
        documents. The agent uses tools (search, read sections, read pages) to
        research the document(s) and produce a comprehensive answer with
        citations. Supports optional structured output via json_schema.


        **This endpoint is synchronous and holds the HTTP connection for the
        entire agent run (typically 1-10 minutes).** For production workloads or
        anything that may run longer, use POST /document/agent/jobs instead — it
        returns a job_id immediately and lets you poll or stream results without
        an HTTP connection limit.
      operationId: document_query_v2_document_agent_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentQueryRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentQueryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /document/agent/jobs:
    post:
      tags:
        - v2-api
        - document-agent
      summary: Enqueue an async document agent job
      description: >-
        Create a long-running document agent job. Returns immediately with a
        `job_id` — use GET /document/agent/jobs/{job_id} to poll for the result
        or GET /document/agent/jobs/{job_id}/stream for live SSE updates.


        Recommended for production workloads, batch evaluation pipelines, or
        anything that may run longer than ~10 minutes. The job runs on a
        background worker pool with 30-minute hard timeout, per-user concurrency
        caps, and automatic refunds on failure.
      operationId: create_document_agent_job_v2_document_agent_jobs_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentQueryRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentAgentJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
        - v2-api
        - document-agent
      summary: List async document agent jobs for the authenticated user
      operationId: list_document_agent_jobs_v2_document_agent_jobs_get
      parameters:
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: 'Filter by status: queued, running, completed, failed, cancelled'
            title: Status
          description: 'Filter by status: queued, running, completed, failed, cancelled'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 20
            title: Limit
        - name: skip
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /document/agent/jobs/{job_id}:
    get:
      tags:
        - v2-api
        - document-agent
      summary: Get the status / result of a document agent job
      operationId: get_document_agent_job_v2_document_agent_jobs__job_id__get
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - v2-api
        - document-agent
      summary: Cancel a running document agent job
      operationId: cancel_document_agent_job_v2_document_agent_jobs__job_id__delete
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /document/agent/jobs/{job_id}/stream:
    get:
      tags:
        - v2-api
        - document-agent
      summary: Stream live updates from a document agent job (SSE)
      operationId: stream_document_agent_job_v2_document_agent_jobs__job_id__stream_get
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /extract:
    post:
      tags:
        - v2-api
        - extract
      summary: Start Extraction
      operationId: start_extraction_v2_extract_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /extract/detect:
    post:
      tags:
        - v2-api
        - extract
      summary: Start Detect Extraction
      operationId: start_detect_extraction_v2_extract_detect_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DetectRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetectResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /extract/detect/{extraction_id}:
    get:
      tags:
        - v2-api
        - extract
      summary: Get Detect Extraction
      operationId: get_detect_extraction_v2_extract_detect__extraction_id__get
      parameters:
        - name: extraction_id
          in: path
          required: true
          schema:
            type: string
            title: Extraction Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetectResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /extract/detect/{extraction_id}/page/{page_number}/image:
    get:
      tags:
        - v2-api
        - extract
      summary: Get Detect Page Image
      operationId: >-
        get_detect_page_image_v2_extract_detect__extraction_id__page__page_number__image_get
      parameters:
        - name: extraction_id
          in: path
          required: true
          schema:
            type: string
            title: Extraction Id
        - name: page_number
          in: path
          required: true
          schema:
            type: integer
            title: Page Number
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /extract/engineering:
    post:
      tags:
        - v2-api
        - extract
      summary: Start Engineering Extraction
      operationId: start_engineering_extraction_v2_extract_engineering_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EngineeringExtractRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngineeringExtractResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /extract/engineering/{extraction_id}:
    get:
      tags:
        - v2-api
        - extract
      summary: Get Engineering Extraction
      operationId: get_engineering_extraction_v2_extract_engineering__extraction_id__get
      parameters:
        - name: extraction_id
          in: path
          required: true
          schema:
            type: string
            title: Extraction Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngineeringExtractResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /extract/engineering/{extraction_id}/query:
    post:
      tags:
        - v2-api
        - extract
      summary: Query Engineering Extraction
      operationId: >-
        query_engineering_extraction_v2_extract_engineering__extraction_id__query_post
      parameters:
        - name: extraction_id
          in: path
          required: true
          schema:
            type: string
            title: Extraction Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EngineeringQueryRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /extract/{extraction_id}:
    get:
      tags:
        - v2-api
        - extract
      summary: Get Extraction
      operationId: get_extraction_v2_extract__extraction_id__get
      parameters:
        - name: extraction_id
          in: path
          required: true
          schema:
            type: string
            title: Extraction Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /extractions:
    get:
      tags:
        - v2-api
        - extract
      summary: List Extractions
      operationId: list_extractions_v2_extractions_get
      parameters:
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: 'Filter by type: table or engineering'
            title: Type
          description: 'Filter by type: table or engineering'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 30
            title: Limit
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /feedback/answer:
    post:
      tags:
        - v2-api
        - feedback
      summary: Submit Answer Feedback
      description: Explicit thumbs up/down on an assistant answer.
      operationId: submit_answer_feedback_v2_feedback_answer_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnswerFeedbackRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /feedback/interaction:
    post:
      tags:
        - v2-api
        - feedback
      summary: Submit Source Interaction
      description: Implicit interaction events (copy, expand, dwell, click-through).
      operationId: submit_source_interaction_v2_feedback_interaction_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceInteractionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /feedback/source:
    post:
      tags:
        - v2-api
        - feedback
      summary: Submit Source Feedback
      description: Per-source helpful/irrelevant/partially_relevant feedback.
      operationId: submit_source_feedback_v2_feedback_source_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceFeedbackRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs:
    get:
      tags:
        - v2-api
        - filesystem
      summary: Fs List
      description: List all filesystem namespaces owned by the caller.
      operationId: fs_list_v2_fs_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    post:
      tags:
        - v2-api
        - filesystem
      summary: Fs Create
      description: |-
        Create a bare filesystem namespace. Returns a source_id you can
        immediately write to via /v2/fs/{source_id}/files.
      operationId: fs_create_v2_fs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFilesystemBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/exec:
    post:
      tags:
        - v2-api
        - filesystem
      summary: Fs Exec
      operationId: fs_exec_v2_fs__source_id__exec_post
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/files:
    put:
      tags:
        - v2-api
        - filesystem
      summary: Fs Write
      operationId: fs_write_v2_fs__source_id__files_put
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteFileBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - v2-api
        - filesystem
      summary: Fs Delete
      operationId: fs_delete_v2_fs__source_id__files_delete
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: path
          in: query
          required: true
          schema:
            type: string
            title: Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/files/batch:
    put:
      tags:
        - v2-api
        - filesystem
      summary: Fs Write Batch
      operationId: fs_write_batch_v2_fs__source_id__files_batch_put
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteBatchBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/find:
    get:
      tags:
        - v2-api
        - filesystem
      summary: Fs Find
      operationId: fs_find_v2_fs__source_id__find_get
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: pattern
          in: query
          required: true
          schema:
            type: string
            description: Glob pattern (e.g. **/*.ts)
            title: Pattern
          description: Glob pattern (e.g. **/*.ts)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/grep:
    post:
      tags:
        - v2-api
        - filesystem
      summary: Fs Grep
      operationId: fs_grep_v2_fs__source_id__grep_post
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrepRequestBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/info:
    get:
      tags:
        - v2-api
        - filesystem
      summary: Fs Info
      operationId: fs_info_v2_fs__source_id__info_get
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/ls:
    get:
      tags:
        - v2-api
        - filesystem
      summary: Fs Ls
      operationId: fs_ls_v2_fs__source_id__ls_get
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: path
          in: query
          required: false
          schema:
            type: string
            default: /
            title: Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/metadata:
    get:
      tags:
        - v2-api
        - filesystem
      summary: Fs Get Metadata
      description: Get filesystem metadata + stats.
      operationId: fs_get_metadata_v2_fs__source_id__metadata_get
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/mkdir:
    post:
      tags:
        - v2-api
        - filesystem
      summary: Fs Mkdir
      operationId: fs_mkdir_v2_fs__source_id__mkdir_post
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MkdirBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/mv:
    post:
      tags:
        - v2-api
        - filesystem
      summary: Fs Mv
      operationId: fs_mv_v2_fs__source_id__mv_post
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/namespace:
    delete:
      tags:
        - v2-api
        - filesystem
      summary: Fs Delete Namespace
      description: |-
        Delete a filesystem namespace and all its files. Only works for
        source_type=filesystem namespaces.
      operationId: fs_delete_namespace_v2_fs__source_id__namespace_delete
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/read:
    get:
      tags:
        - v2-api
        - filesystem
      summary: Fs Read
      operationId: fs_read_v2_fs__source_id__read_get
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: path
          in: query
          required: true
          schema:
            type: string
            description: File path to read
            title: Path
          description: File path to read
        - name: line_start
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            title: Line Start
        - name: line_end
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            title: Line End
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /fs/{source_id}/tree:
    get:
      tags:
        - v2-api
        - filesystem
      summary: Fs Tree
      operationId: fs_tree_v2_fs__source_id__tree_get
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: path
          in: query
          required: false
          schema:
            type: string
            default: /
            title: Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /github/glob:
    post:
      tags:
        - v2-api
        - github-search
      summary: Github Glob
      description: Find files matching a glob pattern in a GitHub repository.
      operationId: github_glob_v2_github_glob_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GitHubGlobRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /github/read:
    post:
      tags:
        - v2-api
        - github-search
      summary: Github Read
      description: Read a file from a GitHub repository with optional line range.
      operationId: github_read_v2_github_read_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GitHubReadRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /github/search:
    post:
      tags:
        - v2-api
        - github-search
      summary: Github Code Search
      description: |-
        Search code in a GitHub repository using GitHub's Code Search API.

        Rate limited to 10 requests/minute by GitHub. Requires authentication
        for private repos (via user's GitHub App installation).
      operationId: github_code_search_v2_github_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GitHubSearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /github/tracer:
    post:
      tags:
        - v2-api
        - github-search
      summary: Create Tracer Job
      description: >-
        Create a Tracer search job.


        Tracer is an autonomous agent that searches GitHub repositories

        to answer your question. Returns immediately with a job_id and
        session_id.

        Use /github/tracer/{job_id}/stream to receive real-time updates.
      operationId: create_tracer_job_v2_github_tracer_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TracerRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
        - v2-api
        - github-search
      summary: List Tracer Jobs
      description: List Tracer jobs for the authenticated user.
      operationId: list_tracer_jobs_v2_github_tracer_get
      parameters:
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by status
            title: Status
          description: Filter by status
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            description: Max results
            default: 50
            title: Limit
          description: Max results
        - name: skip
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            description: Offset for pagination
            default: 0
            title: Skip
          description: Offset for pagination
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /github/tracer/{job_id}:
    delete:
      tags:
        - v2-api
        - github-search
      summary: Delete Tracer Job
      description: Delete a Tracer job by session_id or workflow_run_id.
      operationId: delete_tracer_job_v2_github_tracer__job_id__delete
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
        - v2-api
        - github-search
      summary: Get Tracer Job
      description: Get the status and result of a Tracer search job.
      operationId: get_tracer_job_v2_github_tracer__job_id__get
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /github/tracer/{job_id}/stream:
    get:
      tags:
        - v2-api
        - github-search
      summary: Stream Tracer Job
      description: |-
        Stream real-time updates from a Tracer search job.

        Uses Hatchet's native streaming with MongoDB fallback polling.
        Reconnectable: can reconnect to a running job's stream at any time.
      operationId: stream_tracer_job_v2_github_tracer__job_id__stream_get
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /github/tree/{owner}/{repo}:
    get:
      tags:
        - v2-api
        - github-search
      summary: Github Tree
      description: Get the file tree of a GitHub repository or subdirectory.
      operationId: github_tree_v2_github_tree__owner___repo__get
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
            title: Owner
        - name: repo
          in: path
          required: true
          schema:
            type: string
            title: Repo
        - name: ref
          in: query
          required: false
          schema:
            type: string
            description: Branch, tag, or commit SHA
            default: HEAD
            title: Ref
          description: Branch, tag, or commit SHA
        - name: path
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Subdirectory path
            title: Path
          description: Subdirectory path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /google-drive/install:
    post:
      tags:
        - v2-api
        - v2-api-google-drive
      summary: Generate Install Url
      operationId: generate_install_url_v2_google_drive_install_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleDriveInstallRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /google-drive/install/callback:
    post:
      tags:
        - v2-api
        - v2-api-google-drive
      summary: Handle Oauth Callback
      operationId: handle_oauth_callback_v2_google_drive_install_callback_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleDriveOAuthCallbackRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /google-drive/installations:
    get:
      tags:
        - v2-api
        - v2-api-google-drive
      summary: List Google Drive Installations
      operationId: list_google_drive_installations_v2_google_drive_installations_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /google-drive/installations/{installation_id}:
    get:
      tags:
        - v2-api
        - v2-api-google-drive
      summary: Get Google Drive Installation
      operationId: >-
        get_google_drive_installation_v2_google_drive_installations__installation_id__get
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - v2-api
        - v2-api-google-drive
      summary: Delete Google Drive Installation
      operationId: >-
        delete_google_drive_installation_v2_google_drive_installations__installation_id__delete
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /google-drive/installations/{installation_id}/browse:
    get:
      tags:
        - v2-api
        - v2-api-google-drive
      summary: Browse Google Drive Items
      operationId: >-
        browse_google_drive_items_v2_google_drive_installations__installation_id__browse_get
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
        - name: folder_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Optional Drive folder ID to browse
            title: Folder Id
          description: Optional Drive folder ID to browse
        - name: q
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Optional Drive item name search
            title: Q
          description: Optional Drive item name search
        - name: page_token
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Pagination token from the previous response
            title: Page Token
          description: Pagination token from the previous response
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            description: Maximum Drive items to return
            default: 100
            title: Page Size
          description: Maximum Drive items to return
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /google-drive/installations/{installation_id}/index:
    post:
      tags:
        - v2-api
        - v2-api-google-drive
      summary: Trigger Google Drive Index
      operationId: >-
        trigger_google_drive_index_v2_google_drive_installations__installation_id__index_post
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
                - $ref: >-
                    #/components/schemas/routes__v2__google_drive__GoogleDriveIndexRequest
                - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /google-drive/installations/{installation_id}/selection:
    get:
      tags:
        - v2-api
        - v2-api-google-drive
      summary: Get Google Drive Selection
      operationId: >-
        get_google_drive_selection_v2_google_drive_installations__installation_id__selection_get
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
        - v2-api
        - v2-api-google-drive
      summary: Update Google Drive Selection
      operationId: >-
        update_google_drive_selection_v2_google_drive_installations__installation_id__selection_post
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/routes__v2__google_drive__GoogleDriveSelectionRequest
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /google-drive/installations/{installation_id}/status:
    get:
      tags:
        - v2-api
        - v2-api-google-drive
      summary: Get Google Drive Index Status
      operationId: >-
        get_google_drive_index_status_v2_google_drive_installations__installation_id__status_get
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /google-drive/installations/{installation_id}/sync:
    post:
      tags:
        - v2-api
        - v2-api-google-drive
      summary: Trigger Google Drive Sync
      operationId: >-
        trigger_google_drive_sync_v2_google_drive_installations__installation_id__sync_post
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
                - $ref: >-
                    #/components/schemas/routes__v2__google_drive__GoogleDriveSyncRequest
                - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oracle:
    post:
      summary: Oracle Research
      description: Run Oracle research and return complete result (non-streaming).
      operationId: oracle_research_v2_oracle_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OracleResearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oracle/1m-usage:
    get:
      summary: Get 1M Usage
      description: Get daily usage for 1M context window models.
      operationId: get_1m_usage_v2_oracle_1m_usage_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyUsage1MResponse'
  /oracle/jobs:
    post:
      summary: Create Oracle Job
      description: |-
        Create a new Oracle research job.

        Returns immediately with job_id and session_id.
        Use /oracle/jobs/{job_id}/stream to receive real-time updates.

        Features:
        - Per-user concurrency limit: max 3 concurrent Oracle jobs
        - Job queuing: additional jobs wait in queue
        - 30-minute timeout per job
      operationId: create_oracle_job_v2_oracle_jobs_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OracleResearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      summary: List Oracle Jobs
      description: |-
        List Oracle research jobs for the authenticated user.

        Returns jobs ordered by creation time (newest first).
      operationId: list_oracle_jobs_v2_oracle_jobs_get
      parameters:
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: 'Filter by status: queued, running, completed, failed'
            title: Status
          description: 'Filter by status: queued, running, completed, failed'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 20
            title: Limit
        - name: skip
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oracle/jobs/{job_id}:
    get:
      summary: Get Oracle Job
      description: >-
        Get the status and details of an Oracle research job.


        Returns full job details including result if completed.

        Includes fallback to check Hatchet state if job appears stuck in running
        state.
      operationId: get_oracle_job_v2_oracle_jobs__job_id__get
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      summary: Cancel Oracle Job
      description: |-
        Cancel a running or queued Oracle research job.

        Note: Cancellation is best-effort. The job may complete
        before cancellation takes effect.
      operationId: cancel_oracle_job_v2_oracle_jobs__job_id__delete
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oracle/jobs/{job_id}/stream:
    get:
      summary: Stream Oracle Job
      description: |-
        Stream real-time updates from an Oracle research job.

        Uses Hatchet's native streaming - no Redis required.
        Reconnectable: can reconnect to a running job's stream at any time.
      operationId: stream_oracle_job_v2_oracle_jobs__job_id__stream_get
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oracle/sessions:
    get:
      summary: List Oracle Sessions
      description: |-
        List Oracle research sessions for the authenticated API key.

        This is the new primary endpoint.
        The old /oracle/history endpoint is deprecated but still operational.
      operationId: list_oracle_sessions_v2_oracle_sessions_get
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 20
            title: Limit
        - name: skip
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 0
            default: 0
            title: Skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oracle/sessions/{session_id}:
    get:
      summary: Get Oracle Session Detail
      description: >-
        Retrieve the full details of a single Oracle research session.


        This is the new primary endpoint.

        The old /oracle/history/{session_id} endpoint is deprecated but still
        operational.
      operationId: get_oracle_session_detail_v2_oracle_sessions__session_id__get
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      summary: Delete Oracle Session
      description: Delete an Oracle research session and its associated chat messages.
      operationId: delete_oracle_session_v2_oracle_sessions__session_id__delete
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oracle/sessions/{session_id}/chat/stream:
    post:
      summary: Stream Oracle Session Chat
      description: |-
        Stream a follow-up chat response for an Oracle research session.

        The response is generated as grounded Q&A based on:
        - The original research report
        - Citations and sources discovered during research
        - Previous chat messages in the session

        This is a lightweight chat mode (not a full Oracle research run).
      operationId: >-
        stream_oracle_session_chat_v2_oracle_sessions__session_id__chat_stream_post
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            title: Session Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OracleSessionChatRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oracle/sessions/{session_id}/messages:
    get:
      summary: Get Oracle Session Messages
      description: |-
        Get chat messages for an Oracle research session.

        Returns the conversation history including the original query/report
        and any follow-up messages.
      operationId: get_oracle_session_messages_v2_oracle_sessions__session_id__messages_get
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            title: Session Id
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            default: 100
            title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /packages/grep:
    post:
      tags:
        - v2-api
        - v2-api-package-search
      summary: Grep package source
      description: >-
        Regex search over public package source code (npm, PyPI, crates.io, Go
        modules).
      operationId: package_search_grep_v2_v2_packages_grep_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackageSearchGrepRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /packages/read:
    post:
      tags:
        - v2-api
        - v2-api-package-search
      summary: Read package file
      description: >-
        Read specific lines from a package source file. Max 200 lines per
        request.
      operationId: package_search_read_file_v2_v2_packages_read_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackageSearchReadFileRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /packages/search:
    post:
      tags:
        - v2-api
        - v2-api-package-search
      summary: Semantic package search
      description: >-
        Hybrid semantic + keyword search over package source. 1-5 natural
        language queries.
      operationId: package_search_hybrid_v2_v2_packages_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackageSearchHybridRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /search:
    post:
      tags:
        - v2-api
        - v2-api-search
      summary: Unified search
      description: Single search endpoint with a mode discriminator.
      operationId: unified_search_v2_v2_search_post
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/QuerySearchRequest'
                - $ref: '#/components/schemas/WebSearchRequestWithMode'
                - $ref: '#/components/schemas/DeepResearchRequestWithMode'
                - $ref: '#/components/schemas/UniversalSearchRequestWithMode'
              title: Body
              discriminator:
                propertyName: mode
                mapping:
                  query: '#/components/schemas/QuerySearchRequest'
                  web: '#/components/schemas/WebSearchRequestWithMode'
                  deep: '#/components/schemas/DeepResearchRequestWithMode'
                  universal: '#/components/schemas/UniversalSearchRequestWithMode'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /shell-docs/index:
    post:
      tags:
        - v2-api
        - shell-docs
      summary: Index Docs
      operationId: index_docs_v2_shell_docs_index_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /shell-docs/load:
    get:
      tags:
        - v2-api
        - shell-docs
      summary: Shell Docs Load
      description: >-
        Combined status + dump in one request. Returns status info + files if
        indexed.
      operationId: shell_docs_load_v2_shell_docs_load_get
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
            description: Documentation URL
            title: Url
          description: Documentation URL
        - name: paths_only
          in: query
          required: false
          schema:
            type: boolean
            description: Return paths without content (for lazy loading)
            default: false
            title: Paths Only
          description: Return paths without content (for lazy loading)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /shell-docs/status:
    get:
      tags:
        - v2-api
        - shell-docs
      summary: Check Status
      operationId: check_status_v2_shell_docs_status_get
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
            description: Documentation URL
            title: Url
          description: Documentation URL
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /shell-docs/telemetry:
    post:
      tags:
        - v2-api
        - shell-docs
      summary: Ingest Telemetry
      operationId: ingest_telemetry_v2_shell_docs_telemetry_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelemetryPayload'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /shell-docs/{namespace}/dump:
    get:
      tags:
        - v2-api
        - shell-docs
      summary: Shell Docs Dump
      operationId: shell_docs_dump_v2_shell_docs__namespace__dump_get
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            title: Namespace
        - name: paths_only
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Paths Only
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /shell-docs/{namespace}/find:
    get:
      tags:
        - v2-api
        - shell-docs
      summary: Shell Docs Find
      operationId: shell_docs_find_v2_shell_docs__namespace__find_get
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            title: Namespace
        - name: pattern
          in: query
          required: true
          schema:
            type: string
            description: Glob pattern (e.g. **/*.md)
            title: Pattern
          description: Glob pattern (e.g. **/*.md)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /shell-docs/{namespace}/grep:
    post:
      tags:
        - v2-api
        - shell-docs
      summary: Shell Docs Grep
      operationId: shell_docs_grep_v2_shell_docs__namespace__grep_post
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            title: Namespace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrepRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /shell-docs/{namespace}/info:
    get:
      tags:
        - v2-api
        - shell-docs
      summary: Shell Docs Info
      operationId: shell_docs_info_v2_shell_docs__namespace__info_get
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            title: Namespace
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /shell-docs/{namespace}/ls:
    get:
      tags:
        - v2-api
        - shell-docs
      summary: Shell Docs Ls
      operationId: shell_docs_ls_v2_shell_docs__namespace__ls_get
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            title: Namespace
        - name: path
          in: query
          required: false
          schema:
            type: string
            default: /
            title: Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /shell-docs/{namespace}/read:
    get:
      tags:
        - v2-api
        - shell-docs
      summary: Shell Docs Read
      operationId: shell_docs_read_v2_shell_docs__namespace__read_get
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            title: Namespace
        - name: path
          in: query
          required: true
          schema:
            type: string
            description: File path to read
            title: Path
          description: File path to read
        - name: line_start
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            title: Line Start
        - name: line_end
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            title: Line End
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /shell-docs/{namespace}/tree:
    get:
      tags:
        - v2-api
        - shell-docs
      summary: Shell Docs Tree
      operationId: shell_docs_tree_v2_shell_docs__namespace__tree_get
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            title: Namespace
        - name: path
          in: query
          required: false
          schema:
            type: string
            default: /
            title: Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slack/install:
    post:
      tags:
        - v2-api
        - v2-api-slack
      summary: Generate Install Url
      description: Generate a Slack OAuth authorization URL.
      operationId: generate_install_url_v2_slack_install_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackInstallRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slack/install/callback:
    post:
      tags:
        - v2-api
        - v2-api-slack
      summary: Handle Oauth Callback
      description: >-
        Exchange an OAuth code for tokens and create the installation.


        Called by the frontend callback route after the user authorizes the
        Slack app.
      operationId: handle_oauth_callback_v2_slack_install_callback_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackOAuthCallbackRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slack/install/token:
    post:
      tags:
        - v2-api
        - v2-api-slack
      summary: Register External Token
      description: |-
        Register an external Slack bot token (BYOT).

        For multi-tenant scenarios: your customers provide their Slack bot token
        and you manage it through Nia's API.
      operationId: register_external_token_v2_slack_install_token_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackTokenRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slack/installations:
    get:
      tags:
        - v2-api
        - v2-api-slack
      summary: List Slack Installations
      description: List all Slack workspace connections for the authenticated user/org.
      operationId: list_slack_installations_v2_slack_installations_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /slack/installations/{installation_id}:
    get:
      tags:
        - v2-api
        - v2-api-slack
      summary: Get Slack Installation
      description: Get details for a specific Slack installation.
      operationId: get_slack_installation_v2_slack_installations__installation_id__get
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - v2-api
        - v2-api-slack
      summary: Delete Slack Installation
      description: Disconnect a Slack workspace.
      operationId: >-
        delete_slack_installation_v2_slack_installations__installation_id__delete
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slack/installations/{installation_id}/channels:
    get:
      tags:
        - v2-api
        - v2-api-slack
      summary: List Slack Channels
      description: List available Slack channels from the workspace.
      operationId: >-
        list_slack_channels_v2_slack_installations__installation_id__channels_get
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
        - v2-api
        - v2-api-slack
      summary: Configure Slack Channels
      description: Configure which channels to index.
      operationId: >-
        configure_slack_channels_v2_slack_installations__installation_id__channels_post
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/routes__v2__slack__SlackChannelsConfigRequest
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slack/installations/{installation_id}/grep:
    post:
      tags:
        - v2-api
        - v2-api-slack
      summary: Grep Slack Messages
      description: BM25 keyword search over indexed Slack messages in TurboPuffer.
      operationId: grep_slack_messages_v2_slack_installations__installation_id__grep_post
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackGrepRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slack/installations/{installation_id}/index:
    post:
      tags:
        - v2-api
        - v2-api-slack
      summary: Trigger Slack Index
      description: Trigger a full re-index of the Slack workspace.
      operationId: trigger_slack_index_v2_slack_installations__installation_id__index_post
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slack/installations/{installation_id}/messages:
    get:
      tags:
        - v2-api
        - v2-api-slack
      summary: Read Slack Messages
      description: Read recent messages from a Slack channel (live from Slack API).
      operationId: >-
        read_slack_messages_v2_slack_installations__installation_id__messages_get
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
        - name: channel
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Channel
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slack/installations/{installation_id}/status:
    get:
      tags:
        - v2-api
        - v2-api-slack
      summary: Get Slack Index Status
      description: Get the indexing status for a Slack workspace.
      operationId: >-
        get_slack_index_status_v2_slack_installations__installation_id__status_get
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources:
    get:
      tags:
        - v2-api
        - v2-api-sources
      summary: List Sources
      operationId: list_sources_v2_sources_get
      parameters:
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Filter by source type
            title: Type
          description: Filter by source type
        - name: query
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Search by name or identifier
            title: Query
          description: Search by name or identifier
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by status
            title: Status
          description: Filter by status
        - name: category_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by category
            title: Category Id
          description: Filter by category
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 20
            title: Limit
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
        - v2-api
        - v2-api-sources
      summary: Create Source
      operationId: create_source_v2_sources_post
      parameters:
        - name: organization_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Organization ID for usage tracking
            title: Organization Id
          description: Organization ID for usage tracking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources-summary:
    get:
      tags:
        - v2-api
        - v2-api
      summary: Get sources summary
      description: >-
        Get counts and recent names for all source types. Designed for quick
        inventory checks.
      operationId: get_sources_summary_v2_sources_summary_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourcesSummaryResponse'
  /sources/explore:
    get:
      tags:
        - v2-api
        - v2-api-sources
      summary: Explore Global Sources
      description: Browse the global catalog of publicly indexed sources.
      operationId: explore_global_sources_v2_sources_explore_get
      parameters:
        - name: search
          in: query
          required: false
          schema:
            type: string
            description: Search by URL or name
            default: ''
            title: Search
          description: Search by URL or name
        - name: source_type
          in: query
          required: false
          schema:
            type: string
            description: >-
              Filter by type: repository | documentation | research_paper |
              huggingface_dataset
            default: ''
            title: Source Type
          description: >-
            Filter by type: repository | documentation | research_paper |
            huggingface_dataset
        - name: status
          in: query
          required: false
          schema:
            type: string
            description: Filter by status
            default: indexed
            title: Status
          description: Filter by status
        - name: sort
          in: query
          required: false
          schema:
            type: string
            description: >-
              Sort: recently_indexed | recently_updated | most_tokens |
              most_snippets | most_subscribed | relevance
            default: most_subscribed
            title: Sort
          description: >-
            Sort: recently_indexed | recently_updated | most_tokens |
            most_snippets | most_subscribed | relevance
        - name: order
          in: query
          required: false
          schema:
            type: string
            description: 'Sort direction: asc | desc'
            default: desc
            title: Order
          description: 'Sort direction: asc | desc'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 20
            title: Limit
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources/resolve:
    get:
      tags:
        - v2-api
        - v2-api-sources
      summary: Resolve Source
      operationId: resolve_source_v2_sources_resolve_get
      parameters:
        - name: identifier
          in: query
          required: true
          schema:
            type: string
            description: Display name, URL, or slug
            title: Identifier
          description: Display name, URL, or slug
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceResolveResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources/subscribe:
    post:
      tags:
        - v2-api
        - v2-api-sources
      summary: Subscribe to a global source
      description: >-
        Subscribe to an existing globally indexed public source. Creates a local
        reference for instant access without re-indexing.
      operationId: subscribe_source_v2_sources_subscribe_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalSourceSubscribeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalSourceSubscribeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources/upload-url:
    post:
      tags:
        - v2-api
        - v2-api-sources
      summary: Get PDF upload URL
      description: >-
        Generate a signed URL for direct PDF upload. Use the returned gcs_path
        in POST /v2/sources.
      operationId: create_source_upload_url_v2_sources_upload_url_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceUploadUrlRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceUploadUrlResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources/{source_id}:
    get:
      tags:
        - v2-api
        - v2-api-sources
      summary: Get Source
      operationId: get_source_v2_sources__source_id__get
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
        - v2-api
        - v2-api-sources
      summary: Update Source
      operationId: update_source_v2_sources__source_id__patch
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - v2-api
        - v2-api-sources
      summary: Delete Source
      operationId: delete_source_v2_sources__source_id__delete
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceDeleteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources/{source_id}/annotations:
    get:
      tags:
        - v2-api
        - v2-api-sources
      summary: List Source Annotations
      operationId: list_source_annotations_v2_sources__source_id__annotations_get
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SourceAnnotation'
                title: >-
                  Response List Source Annotations V2 Sources  Source Id 
                  Annotations Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
        - v2-api
        - v2-api-sources
      summary: Create Source Annotation
      operationId: create_source_annotation_v2_sources__source_id__annotations_post
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceAnnotationCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceCurationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources/{source_id}/annotations/{annotation_id}:
    patch:
      tags:
        - v2-api
        - v2-api-sources
      summary: Update Source Annotation
      operationId: >-
        update_source_annotation_v2_sources__source_id__annotations__annotation_id__patch
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: annotation_id
          in: path
          required: true
          schema:
            type: string
            title: Annotation Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceAnnotationUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceCurationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - v2-api
        - v2-api-sources
      summary: Delete Source Annotation
      operationId: >-
        delete_source_annotation_v2_sources__source_id__annotations__annotation_id__delete
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: annotation_id
          in: path
          required: true
          schema:
            type: string
            title: Annotation Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceCurationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources/{source_id}/classification:
    get:
      tags:
        - v2-api
        - v2-api-sources
      summary: Get Source Classification
      operationId: get_source_classification_v2_sources__source_id__classification_get
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
        - v2-api
        - v2-api-sources
      summary: Update Source Classification
      operationId: update_source_classification_v2_sources__source_id__classification_patch
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClassifyLocalFolderRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources/{source_id}/content:
    get:
      tags:
        - v2-api
        - v2-api-sources
      summary: Get Source Content
      operationId: get_source_content_v2_sources__source_id__content_get
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
        - name: path
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Path or virtual path
            title: Path
          description: Path or virtual path
        - name: url
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Direct URL (documentation)
            title: Url
          description: Direct URL (documentation)
        - name: branch
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Repository branch
            title: Branch
          description: Repository branch
        - name: page
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: PDF page number
            title: Page
          description: PDF page number
        - name: tree_node_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: PDF tree node identifier
            title: Tree Node Id
          description: PDF tree node identifier
        - name: line_start
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Starting line number
            title: Line Start
          description: Starting line number
        - name: line_end
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Ending line number
            title: Line End
          description: Ending line number
        - name: max_length
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Maximum content length
            title: Max Length
          description: Maximum content length
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceContentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources/{source_id}/curation:
    get:
      tags:
        - v2-api
        - v2-api-sources
      summary: Get Source Curation
      operationId: get_source_curation_v2_sources__source_id__curation_get
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceCurationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
        - v2-api
        - v2-api-sources
      summary: Update Source Curation
      operationId: update_source_curation_v2_sources__source_id__curation_put
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceCurationUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceCurationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources/{source_id}/grep:
    post:
      tags:
        - v2-api
        - v2-api-sources
      summary: Grep Source
      operationId: grep_source_v2_sources__source_id__grep_post
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources/{source_id}/sync:
    post:
      tags:
        - v2-api
        - v2-api-sources
      summary: Sync Source
      operationId: sync_source_v2_sources__source_id__sync_post
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sources/{source_id}/tree:
    get:
      tags:
        - v2-api
        - v2-api-sources
      summary: Get Source Tree
      operationId: get_source_tree_v2_sources__source_id__tree_get
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - repository
                  - documentation
                  - research_paper
                  - huggingface_dataset
                  - local_folder
                  - slack
                  - google_drive
                  - connector
                type: string
              - type: 'null'
            description: Source type hint
            title: Type
          description: Source type hint
        - name: branch
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Repository branch
            title: Branch
          description: Repository branch
        - name: max_depth
          in: query
          required: false
          schema:
            type: integer
            maximum: 20
            minimum: 1
            default: 10
            title: Max Depth
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /usage:
    get:
      tags:
        - v2-api
        - v2-api
      summary: Get usage summary
      description: >-
        Get usage counts and limits for current billing period (queries,
        indexing, oracle, etc.).
      operationId: get_usage_summary_v2_v2_usage_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageSummaryResponse'
  /vaults:
    post:
      tags:
        - v2-api
        - vaults
      summary: Create Vault
      description: >-
        Create a new vault.


        Body: {display_name: str, description?: str, source_ids?: [str],
        schema_md?: str}


        Bootstraps the vault namespace with schema.md/index.md/log.md/META.md.

        Does NOT auto-trigger ingest — call POST /v2/vaults/{id}/run with

        mode=ingest after creation if you want immediate ingestion.
      operationId: create_vault_v2_vaults_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Create Vault V2 Vaults Post
    get:
      tags:
        - v2-api
        - vaults
      summary: List Vaults
      description: List vaults owned by the calling user / org.
      operationId: list_vaults_v2_vaults_get
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            default: 100
            title: Limit
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Vaults V2 Vaults Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /vaults/available-sources:
    get:
      tags:
        - v2-api
        - vaults
      summary: List Available Sources
      description: >-
        Return every source the user can add to a vault.


        Merges data_sources (excluding vaults), local_folders, and projects into
        a

        single list with a unified shape so the frontend picker shows
        everything.
      operationId: list_available_sources_v2_vaults_available_sources_get
      parameters:
        - name: q
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Search filter on display_name / url
            title: Q
          description: Search filter on display_name / url
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 2000
            minimum: 1
            default: 500
            title: Limit
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: >-
                  Response List Available Sources V2 Vaults Available Sources
                  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /vaults/{vault_id}:
    get:
      tags:
        - v2-api
        - vaults
      summary: Get Vault
      description: Get vault metadata and current workflow status.
      operationId: get_vault_v2_vaults__vault_id__get
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
            title: Vault Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Vault V2 Vaults  Vault Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - v2-api
        - vaults
      summary: Delete Vault
      description: >-
        Delete a vault.


        Cleans up Postgres files AND TurboPuffer chunks. Order matters: drop

        TurboPuffer first, then PG, then Mongo. If any step fails before the
        Mongo

        delete, the vault row remains so the user can retry without losing

        accounting state.
      operationId: delete_vault_v2_vaults__vault_id__delete
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
            title: Vault Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Delete Vault V2 Vaults  Vault Id  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
        - v2-api
        - vaults
      summary: Patch Vault
      description: |-
        Update vault metadata (display_name, description, schema_md).

        When schema_md is updated, the new content is also written into the
        vault namespace as `/schema.md` so the bash session sees it immediately.
      operationId: patch_vault_v2_vaults__vault_id__patch
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
            title: Vault Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Patch Vault V2 Vaults  Vault Id  Patch
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /vaults/{vault_id}/agent:
    post:
      tags:
        - v2-api
        - vaults
      summary: Vault Agent
      description: |-
        Stream an AI agent response that can search/read the vault.

        Returns an SSE stream of events (same shape as the document agent).
        Charges one QUERY credit per call; refunds on failure.
      operationId: vault_agent_v2_vaults__vault_id__agent_post
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
            title: Vault Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /vaults/{vault_id}/cancel:
    post:
      tags:
        - v2-api
        - vaults
      summary: Cancel Vault Workflow
      description: Cancel an in-flight vault workflow run, if any.
      operationId: cancel_vault_workflow_v2_vaults__vault_id__cancel_post
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
            title: Vault Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: >-
                  Response Cancel Vault Workflow V2 Vaults  Vault Id  Cancel
                  Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /vaults/{vault_id}/graph:
    get:
      tags:
        - v2-api
        - vaults
      summary: Vault Graph
      description: |-
        Return the wikilink graph as nodes + edges for visualization.

        Walks all concept/entity/note pages, parses [[wikilinks]], and builds a
        force-directed-ready JSON structure. No LLM calls — pure file parsing.
      operationId: vault_graph_v2_vaults__vault_id__graph_get
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
            title: Vault Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Vault Graph V2 Vaults  Vault Id  Graph Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /vaults/{vault_id}/load:
    get:
      tags:
        - v2-api
        - vaults
      summary: Load Vault
      description: >-
        Bootstrap dump for the `nia vault open` bash session.


        Mirrors the shape of /shell-docs/load. Returns vault metadata and either

        full file contents or just paths (for vaults > 1000 files).


        Up to 10000 files are returned (matches DIR_LISTING_LIMIT in
        fs_service.py).
      operationId: load_vault_v2_vaults__vault_id__load_get
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
            title: Vault Id
        - name: paths_only
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Paths Only
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Load Vault V2 Vaults  Vault Id  Load Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /vaults/{vault_id}/run:
    post:
      tags:
        - v2-api
        - vaults
      summary: Run Vault Workflow
      description: >-
        Trigger a vault_workflow run. Body: {mode: ingest|sync|lint|refresh,
        source_ids?: [], model?: str, force?: bool}
      operationId: run_vault_workflow_v2_vaults__vault_id__run_post
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
            title: Vault Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Run Vault Workflow V2 Vaults  Vault Id  Run Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /vaults/{vault_id}/search:
    post:
      tags:
        - v2-api
        - vaults
      summary: Search Vault
      description: >-
        Hybrid search scoped to this vault's namespace.


        Returns embedded vault pages as ranked results with citations. The vault

        namespace was populated by the existing `fs_sync_workflow` mirroring
        every

        write into TurboPuffer (see routes/v2/fs.py:294-313).


        Telemetry: emits both `store_api_activity` (for the user-facing activity

        feed) and `store_retrieval_log` (for the training-data pipeline) so
        vault

        searches show up alongside every other retrieval call. Two retrieval
        logs

        are written for the two-tier strategy: a `vector` log for the
        TurboPuffer

        path, and a `regex` log if the PG grep fallback fires.
      operationId: search_vault_v2_vaults__vault_id__search_post
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
            title: Vault Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Search Vault V2 Vaults  Vault Id  Search Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /vaults/{vault_id}/sources:
    get:
      tags:
        - v2-api
        - vaults
      summary: List Vault Sources
      description: List the source IDs currently linked to this vault, with metadata.
      operationId: list_vault_sources_v2_vaults__vault_id__sources_get
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
            title: Vault Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Vault Sources V2 Vaults  Vault Id  Sources Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
        - v2-api
        - vaults
      summary: Add Vault Source
      description: Add a source to the vault's source_ids[]. Idempotent.
      operationId: add_vault_source_v2_vaults__vault_id__sources_post
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
            title: Vault Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Add Vault Source V2 Vaults  Vault Id  Sources Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /vaults/{vault_id}/sources/{source_id}:
    delete:
      tags:
        - v2-api
        - vaults
      summary: Remove Vault Source
      description: Remove a source from the vault's source_ids[]. Idempotent.
      operationId: remove_vault_source_v2_vaults__vault_id__sources__source_id__delete
      parameters:
        - name: vault_id
          in: path
          required: true
          schema:
            type: string
            title: Vault Id
        - name: source_id
          in: path
          required: true
          schema:
            type: string
            title: Source Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: >-
                  Response Remove Vault Source V2 Vaults  Vault Id  Sources 
                  Source Id  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /x/installations:
    get:
      tags:
        - v2-api
        - v2-api-x
      summary: List X Installations
      operationId: list_x_installations_v2_x_installations_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    post:
      tags:
        - v2-api
        - v2-api-x
      summary: Create X Installation
      operationId: create_x_installation_v2_x_installations_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/routes__v2__x__XInstallationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /x/installations/{installation_id}:
    get:
      tags:
        - v2-api
        - v2-api-x
      summary: Get X Installation
      operationId: get_x_installation_v2_x_installations__installation_id__get
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - v2-api
        - v2-api-x
      summary: Delete X Installation
      operationId: delete_x_installation_v2_x_installations__installation_id__delete
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /x/installations/{installation_id}/index:
    post:
      tags:
        - v2-api
        - v2-api-x
      summary: Trigger X Index
      operationId: trigger_x_index_v2_x_installations__installation_id__index_post
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /x/installations/{installation_id}/status:
    get:
      tags:
        - v2-api
        - v2-api-x
      summary: Get X Index Status
      operationId: get_x_index_status_v2_x_installations__installation_id__status_get
      parameters:
        - name: installation_id
          in: path
          required: true
          schema:
            type: string
            title: Installation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AdvisorRequest:
      properties:
        query:
          type: string
          title: Query
          description: User's question
        codebase:
          $ref: '#/components/schemas/CodebaseContext'
          description: User's codebase context
        search_scope:
          anyOf:
            - $ref: '#/components/schemas/SearchScope'
            - type: 'null'
          description: Nia search scope
        output_format:
          type: string
          enum:
            - explanation
            - checklist
            - diff
            - structured
          title: Output Format
          description: Output format
          default: explanation
      type: object
      required:
        - query
        - codebase
      title: AdvisorRequest
      description: Request model for advisor endpoint.
    AdvisorResponse:
      properties:
        advice:
          type: string
          title: Advice
          description: Tailored advice
        sources_searched:
          type: integer
          title: Sources Searched
          description: Number of sources searched
          default: 0
        output_format:
          type: string
          title: Output Format
          default: explanation
      type: object
      required:
        - advice
      title: AdvisorResponse
      description: Response model for advisor endpoint.
    AnalyzeResponse:
      properties:
        manifest_type:
          type: string
          title: Manifest Type
        total_dependencies:
          type: integer
          title: Total Dependencies
        dependencies:
          items:
            $ref: '#/components/schemas/DependencyItem'
          type: array
          title: Dependencies
        mappings:
          items:
            $ref: '#/components/schemas/MappingItem'
          type: array
          title: Mappings
        unmapped_count:
          type: integer
          title: Unmapped Count
        unmapped_packages:
          items:
            type: string
          type: array
          title: Unmapped Packages
      type: object
      required:
        - manifest_type
        - total_dependencies
        - dependencies
        - mappings
        - unmapped_count
        - unmapped_packages
      title: AnalyzeResponse
    AnswerFeedbackRequest:
      properties:
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Message Id
        signal:
          type: string
          enum:
            - thumbs_up
            - thumbs_down
          title: Signal
        retrieval_log_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Retrieval Log Id
        comment:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Comment
      type: object
      required:
        - signal
      title: AnswerFeedbackRequest
    Body_upload_and_subscribe_v2_dependencies_upload_post:
      properties:
        file:
          type: string
          format: binary
          title: File
          description: Manifest file to upload
        include_dev_dependencies:
          type: boolean
          title: Include Dev Dependencies
          description: Include dev dependencies
          default: false
        max_new_indexes:
          type: integer
          maximum: 500
          minimum: 0
          title: Max New Indexes
          description: Max new indexes to start
          default: 150
      type: object
      required:
        - file
      title: Body_upload_and_subscribe_v2_dependencies_upload_post
    BootstrapKeyRequest:
      properties:
        bootstrap_token:
          type: string
          title: Bootstrap Token
          description: Token from /v2/auth/signup response
      type: object
      required:
        - bootstrap_token
      title: BootstrapKeyRequest
    BootstrapKeyResponse:
      properties:
        api_key:
          type: string
          title: Api Key
          description: >-
            Your new nk_ API key — store it securely, it cannot be retrieved
            again
        api_key_id:
          type: string
          title: Api Key Id
        user_id:
          type: string
          title: User Id
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
      type: object
      required:
        - api_key
        - api_key_id
        - user_id
      title: BootstrapKeyResponse
    BulkDeleteItem:
      properties:
        id:
          type: string
          title: Id
          description: Resource ID
        type:
          type: string
          enum:
            - repository
            - documentation
            - research_paper
            - context
            - local_folder
          title: Type
          description: Resource type
      type: object
      required:
        - id
        - type
      title: BulkDeleteItem
      description: Single item to delete
    BulkDeleteRequest:
      properties:
        items:
          items:
            $ref: '#/components/schemas/BulkDeleteItem'
          type: array
          minItems: 1
          title: Items
          description: Items to delete
      type: object
      required:
        - items
      title: BulkDeleteRequest
      description: Request for bulk deletion
    BulkDeleteResponse:
      properties:
        deleted:
          type: integer
          title: Deleted
          description: Number of successfully deleted items
        failed:
          type: integer
          title: Failed
          description: Number of failed deletions
        results:
          items:
            $ref: '#/components/schemas/BulkDeleteResult'
          type: array
          title: Results
          description: Per-item results
      type: object
      required:
        - deleted
        - failed
        - results
      title: BulkDeleteResponse
      description: Response for bulk deletion
    BulkDeleteResult:
      properties:
        id:
          type: string
          title: Id
        type:
          type: string
          title: Type
        success:
          type: boolean
          title: Success
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
      type: object
      required:
        - id
        - type
        - success
      title: BulkDeleteResult
      description: Result of a single delete operation
    CategoryListCompatResponse:
      properties:
        items:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Items
          description: List of categories
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
          description: Pagination metadata
        categories:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Categories
          description: Legacy categories list
        total:
          type: integer
          title: Total
          description: Legacy total count
      type: object
      required:
        - pagination
        - total
      title: CategoryListCompatResponse
      description: Backwards-compatible category list response.
    CategoryResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        user_id:
          type: string
          title: User Id
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
        color:
          anyOf:
            - type: string
            - type: 'null'
          title: Color
        order:
          type: integer
          title: Order
          default: 0
        created_at:
          type: string
          title: Created At
        updated_at:
          type: string
          title: Updated At
      type: object
      required:
        - id
        - name
        - user_id
        - created_at
        - updated_at
      title: CategoryResponse
    ClassifyLocalFolderRequest:
      properties:
        categories:
          items:
            type: string
          type: array
          maxItems: 10
          minItems: 2
          title: Categories
          description: Categories to classify content into (2-10 categories)
        include_uncategorized:
          type: boolean
          title: Include Uncategorized
          description: Whether to include an 'Uncategorized' bucket for edge cases
          default: true
      type: object
      required:
        - categories
      title: ClassifyLocalFolderRequest
      description: Request to classify local folder content.
    CodebaseContext:
      properties:
        files:
          additionalProperties:
            type: string
          type: object
          title: Files
          description: Map of file_path -> file_content
        file_tree:
          anyOf:
            - type: string
            - type: 'null'
          title: File Tree
          description: Directory structure (from tree command or similar)
        dependencies:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Dependencies
          description: 'Dependency files: package.json, requirements.txt, etc.'
        git_diff:
          anyOf:
            - type: string
            - type: 'null'
          title: Git Diff
          description: Git diff for migration/upgrade scenarios
        summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Summary
          description: High-level description of the codebase
        focus_paths:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Focus Paths
          description: Paths to prioritize in analysis
      type: object
      title: CodebaseContext
      description: Structured codebase context from the user.
    ContextListCompatResponse:
      properties:
        items:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Items
          description: List of contexts
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
          description: Pagination metadata
        contexts:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Contexts
          description: Legacy contexts list
        total:
          type: integer
          title: Total
          description: Legacy total count
      type: object
      required:
        - pagination
        - total
      title: ContextListCompatResponse
      description: Backwards-compatible context list response.
    ContextSearchResponse:
      properties:
        contexts:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Contexts
          description: Matching contexts
        search_query:
          type: string
          title: Search Query
          description: The search query used
        total_results:
          type: integer
          title: Total Results
          description: Total number of results
          default: 0
      type: object
      required:
        - search_query
      title: ContextSearchResponse
      description: Response for text search in contexts.
    ContextSemanticSearchMetadata:
      properties:
        search_type:
          type: string
          title: Search Type
          description: Type of search performed
          default: semantic
        total_results:
          type: integer
          title: Total Results
          description: Number of results
          default: 0
        vector_matches:
          type: integer
          title: Vector Matches
          description: Number of vector matches
          default: 0
        mongodb_matches:
          type: integer
          title: Mongodb Matches
          description: Number of MongoDB matches
          default: 0
      type: object
      title: ContextSemanticSearchMetadata
      description: Metadata for semantic search.
    ContextSemanticSearchResponse:
      properties:
        results:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Results
          description: Search results with scores
        search_query:
          type: string
          title: Search Query
          description: The search query used
        search_metadata:
          $ref: '#/components/schemas/ContextSemanticSearchMetadata'
          description: Search metadata
        suggestions:
          $ref: '#/components/schemas/ContextSemanticSearchSuggestions'
          description: Search suggestions
      type: object
      required:
        - search_query
        - search_metadata
        - suggestions
      title: ContextSemanticSearchResponse
      description: Response for semantic search in contexts.
    ContextSemanticSearchSuggestions:
      properties:
        related_tags:
          items:
            type: string
          type: array
          title: Related Tags
          description: Related tags
        workspaces:
          items:
            type: string
          type: array
          title: Workspaces
          description: Related workspaces
        tips:
          items:
            type: string
          type: array
          title: Tips
          description: Search tips
      type: object
      title: ContextSemanticSearchSuggestions
      description: Suggestions from semantic search.
    ContextShareRequest:
      properties:
        title:
          type: string
          maxLength: 200
          minLength: 1
          title: Title
        summary:
          type: string
          maxLength: 1000
          minLength: 10
          title: Summary
        content:
          type: string
          minLength: 50
          title: Content
        tags:
          items:
            type: string
          type: array
          title: Tags
        agent_source:
          type: string
          title: Agent Source
          description: Which agent created this context
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
        nia_references:
          anyOf:
            - $ref: '#/components/schemas/routes__v2__contexts__NiaReferences-Input'
            - type: 'null'
        edited_files:
          items:
            $ref: '#/components/schemas/routes__v2__contexts__EditedFile'
          type: array
          title: Edited Files
        memory_type:
          type: string
          enum:
            - scratchpad
            - episodic
            - fact
            - procedural
          title: Memory Type
          description: >-
            Memory type: scratchpad (1hr), episodic (7d), fact (permanent),
            procedural (permanent)
          default: episodic
        ttl_seconds:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Ttl Seconds
          description: Custom TTL in seconds. If not set, uses memory_type default.
        lineage:
          anyOf:
            - $ref: '#/components/schemas/LineageInput'
            - type: 'null'
          description: Provenance tracking for this context
      type: object
      required:
        - title
        - summary
        - content
        - agent_source
      title: ContextShareRequest
      description: Request model for creating a shared context.
    ContextShareResponse:
      properties:
        id:
          type: string
          title: Id
        user_id:
          type: string
          title: User Id
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
        title:
          type: string
          title: Title
        summary:
          type: string
          title: Summary
        content:
          type: string
          title: Content
        tags:
          items:
            type: string
          type: array
          title: Tags
        agent_source:
          type: string
          title: Agent Source
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        nia_references:
          anyOf:
            - $ref: '#/components/schemas/NiaReferences-Output'
            - type: 'null'
        edited_files:
          items:
            $ref: '#/components/schemas/EditedFile-Output'
          type: array
          title: Edited Files
        memory_type:
          type: string
          enum:
            - scratchpad
            - episodic
            - fact
            - procedural
          title: Memory Type
          default: episodic
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Expires At
        lineage:
          anyOf:
            - $ref: '#/components/schemas/LineageMetadata'
            - type: 'null'
        category_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Category Id
      type: object
      required:
        - id
        - user_id
        - title
        - summary
        - content
        - tags
        - agent_source
        - created_at
        - metadata
      title: ContextShareResponse
      description: Response model for context operations.
    ContextShareUpdateRequest:
      properties:
        title:
          anyOf:
            - type: string
              maxLength: 200
              minLength: 1
            - type: 'null'
          title: Title
        summary:
          anyOf:
            - type: string
              maxLength: 1000
              minLength: 10
            - type: 'null'
          title: Summary
        content:
          anyOf:
            - type: string
              minLength: 50
            - type: 'null'
          title: Content
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tags
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
        nia_references:
          anyOf:
            - $ref: '#/components/schemas/routes__v2__contexts__NiaReferences-Input'
            - type: 'null'
        edited_files:
          anyOf:
            - items:
                $ref: '#/components/schemas/routes__v2__contexts__EditedFile'
              type: array
            - type: 'null'
          title: Edited Files
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
        memory_type:
          anyOf:
            - type: string
              enum:
                - scratchpad
                - episodic
                - fact
                - procedural
            - type: 'null'
          title: Memory Type
          description: Memory type
        ttl_seconds:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Ttl Seconds
          description: Custom TTL in seconds
        lineage:
          anyOf:
            - $ref: '#/components/schemas/LineageInput'
            - type: 'null'
          description: Provenance tracking
      type: object
      title: ContextShareUpdateRequest
      description: Request model for updating a shared context.
    CreateFilesystemBody:
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
          description: Display name for the filesystem
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Optional description
      type: object
      required:
        - name
      title: CreateFilesystemBody
    DailyUsage1MResponse:
      properties:
        used:
          type: integer
          title: Used
          description: Number of 1M context requests used today
        limit:
          type: integer
          title: Limit
          description: Daily limit for 1M context requests
        remaining:
          type: integer
          title: Remaining
          description: Remaining 1M context requests today
      type: object
      required:
        - used
        - limit
        - remaining
      title: DailyUsage1MResponse
    DatabaseFileItem:
      properties:
        filename:
          type: string
          title: Filename
          description: Original filename (e.g., 'chat.db')
        content:
          type: string
          title: Content
          description: Base64-encoded database file content
      type: object
      required:
        - filename
        - content
      title: DatabaseFileItem
      description: A database file for upload.
    DeepResearchRequestWithMode:
      properties:
        query:
          type: string
          title: Query
          description: Research question
        output_format:
          anyOf:
            - type: string
            - type: 'null'
          title: Output Format
          description: Optional structure hint
        verbose:
          type: boolean
          title: Verbose
          description: Include verbose trace output
          default: false
        mode:
          type: string
          const: deep
          title: Mode
          description: Search mode discriminator
          default: deep
      type: object
      required:
        - query
      title: DeepResearchRequestWithMode
    DeleteResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the deletion succeeded
        message:
          type: string
          title: Message
          description: Status message
      type: object
      required:
        - success
        - message
      title: DeleteResponse
      description: Response for delete operations.
    DependencyAnalyzeRequest:
      properties:
        manifest_content:
          type: string
          title: Manifest Content
          description: Raw content of the manifest file
        manifest_type:
          anyOf:
            - type: string
              enum:
                - package.json
                - requirements.txt
                - pyproject.toml
                - Cargo.toml
                - go.mod
                - Gemfile
            - type: 'null'
          title: Manifest Type
          description: Manifest type. Auto-detected if not provided.
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
          description: Original filename for type detection
      type: object
      required:
        - manifest_content
      title: DependencyAnalyzeRequest
    DependencyItem:
      properties:
        name:
          type: string
          title: Name
        version:
          anyOf:
            - type: string
            - type: 'null'
          title: Version
        registry:
          type: string
          title: Registry
        is_dev:
          type: boolean
          title: Is Dev
      type: object
      required:
        - name
        - version
        - registry
        - is_dev
      title: DependencyItem
    DependencySubscribeRequest:
      properties:
        manifest_content:
          type: string
          title: Manifest Content
          description: Raw content of the manifest file
        manifest_type:
          anyOf:
            - type: string
              enum:
                - package.json
                - requirements.txt
                - pyproject.toml
                - Cargo.toml
                - go.mod
                - Gemfile
            - type: 'null'
          title: Manifest Type
          description: Manifest type. Auto-detected if not provided.
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
          description: Original filename for type detection
        include_dev_dependencies:
          type: boolean
          title: Include Dev Dependencies
          description: Include devDependencies/dev-dependencies
          default: false
        max_new_indexes:
          type: integer
          maximum: 500
          minimum: 0
          title: Max New Indexes
          description: Max number of new indexes to start (0-500)
          default: 150
      type: object
      required:
        - manifest_content
      title: DependencySubscribeRequest
    DetectRequest:
      properties:
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        source_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Id
        page_range:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Range
        include_symbols:
          type: boolean
          title: Include Symbols
          default: false
        filter_pattern:
          anyOf:
            - type: string
            - type: 'null'
          title: Filter Pattern
      type: object
      title: DetectRequest
    DetectResponse:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          title: Status
        progress:
          type: integer
          title: Progress
          default: 0
        type:
          type: string
          title: Type
          default: detect
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        source_display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Display Name
        page_range:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Range
        result:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Result
        page_count:
          type: integer
          title: Page Count
          default: 0
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        created_at:
          type: string
          title: Created At
        updated_at:
          type: string
          title: Updated At
      type: object
      required:
        - id
        - status
        - created_at
        - updated_at
      title: DetectResponse
    DocumentAgentJobResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Workflow run id — pass to GET/stream/cancel endpoints
        status:
          type: string
          title: Status
          description: Initial status — usually 'queued'
        created_at:
          type: string
          title: Created At
        message:
          type: string
          title: Message
      type: object
      required:
        - job_id
        - status
        - created_at
        - message
      title: DocumentAgentJobResponse
      description: Returned by POST /document/agent/jobs.
    DocumentCitation:
      properties:
        content:
          type: string
          title: Content
        page_number:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page Number
        section_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Section Id
        section_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Section Title
        section_path:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Section Path
        tool_source:
          type: string
          title: Tool Source
        source_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Id
        source_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Name
      type: object
      required:
        - content
        - tool_source
      title: DocumentCitation
      description: A citation from the document agent with full location metadata.
    DocumentQueryRequest:
      properties:
        source_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Id
          description: Data source ID of a single indexed document
        source_ids:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 50
            - type: 'null'
          title: Source Ids
          description: List of data source IDs for multi-document queries (max 50)
        query:
          type: string
          maxLength: 10000
          minLength: 1
          title: Query
          description: Question to ask about the document(s)
        json_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Json Schema
          description: JSON Schema for structured output
        model:
          type: string
          title: Model
          description: Model to use (claude-opus-4-7, claude-sonnet-4-5-20250929, etc.)
          default: claude-opus-4-7
        thinking_enabled:
          type: boolean
          title: Thinking Enabled
          description: Enable extended thinking
          default: true
        thinking_budget:
          type: integer
          maximum: 50000
          minimum: 1000
          title: Thinking Budget
          description: >-
            Token budget for thinking (ignored for adaptive models like Opus
            4.7)
          default: 10000
        stream:
          type: boolean
          title: Stream
          description: Stream response as SSE events
          default: false
      type: object
      required:
        - query
      title: DocumentQueryRequest
      description: Request for the v2 document/agent endpoint.
    DocumentQueryResponse:
      properties:
        answer:
          type: string
          title: Answer
        citations:
          items:
            $ref: '#/components/schemas/DocumentCitation'
          type: array
          title: Citations
        structured_output:
          anyOf:
            - {}
            - type: 'null'
          title: Structured Output
        model:
          type: string
          title: Model
        usage:
          anyOf:
            - additionalProperties:
                type: integer
              type: object
            - type: 'null'
          title: Usage
      type: object
      required:
        - answer
        - model
      title: DocumentQueryResponse
      description: Response from the v2 document/agent endpoint.
    EditedFile-Output:
      properties:
        file_path:
          type: string
          title: File Path
          description: Path to the file
        operation:
          type: string
          title: Operation
          description: 'Type: ''created'', ''modified'', ''deleted'''
        changes_description:
          type: string
          title: Changes Description
          description: Brief description of changes
        key_changes:
          items:
            type: string
          type: array
          title: Key Changes
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          description: Programming language of the file
      type: object
      required:
        - file_path
        - operation
        - changes_description
      title: EditedFile
      description: Represents a file that was modified during the conversation.
    EngineeringExtractRequest:
      properties:
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        source_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Id
        page_range:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Range
        accuracy_mode:
          type: string
          title: Accuracy Mode
          default: fast
      type: object
      title: EngineeringExtractRequest
    EngineeringExtractResponse:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          title: Status
        progress:
          type: integer
          title: Progress
          default: 0
        type:
          type: string
          title: Type
          default: engineering
        accuracy_mode:
          type: string
          title: Accuracy Mode
          default: fast
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        source_display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Display Name
        page_range:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Range
        result:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Result
        page_count:
          type: integer
          title: Page Count
          default: 0
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        chat_messages:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Chat Messages
        created_at:
          type: string
          title: Created At
        updated_at:
          type: string
          title: Updated At
      type: object
      required:
        - id
        - status
        - created_at
        - updated_at
      title: EngineeringExtractResponse
    EngineeringQueryRequest:
      properties:
        query:
          type: string
          title: Query
        conversation_history:
          items:
            additionalProperties:
              type: string
            type: object
          type: array
          title: Conversation History
      type: object
      required:
        - query
      title: EngineeringQueryRequest
    ExecBody:
      properties:
        command:
          type: string
          title: Command
          description: Bash command to execute (e.g. 'cat /file.py', 'grep -rn pattern .')
        cwd:
          type: string
          title: Cwd
          description: Working directory for relative paths
          default: /
      type: object
      required:
        - command
      title: ExecBody
    ExtractRequest:
      properties:
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        source_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Id
        page_range:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Range
        json_schema:
          additionalProperties: true
          type: object
          title: Json Schema
      type: object
      required:
        - json_schema
      title: ExtractRequest
    ExtractResponse:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          title: Status
        progress:
          type: integer
          title: Progress
          default: 0
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        source_display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Display Name
        page_range:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Range
        records:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Records
        record_count:
          type: integer
          title: Record Count
          default: 0
        page_count:
          type: integer
          title: Page Count
          default: 0
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        created_at:
          type: string
          title: Created At
        updated_at:
          type: string
          title: Updated At
      type: object
      required:
        - id
        - status
        - created_at
        - updated_at
      title: ExtractResponse
    FileItem:
      properties:
        path:
          type: string
          title: Path
          description: Relative file path (e.g., 'src/main.py')
        content:
          type: string
          title: Content
          description: File content as UTF-8 string
      type: object
      required:
        - path
        - content
      title: FileItem
      description: A single file in the upload batch.
    GitHubGlobRequest:
      properties:
        repository:
          type: string
          title: Repository
          description: Repository in owner/repo format
        pattern:
          type: string
          title: Pattern
          description: Glob pattern (e.g., '*.py', 'src/**/*.ts')
        ref:
          type: string
          title: Ref
          description: Branch, tag, or commit SHA
          default: HEAD
      type: object
      required:
        - repository
        - pattern
      title: GitHubGlobRequest
    GitHubReadRequest:
      properties:
        repository:
          type: string
          title: Repository
          description: Repository in owner/repo format
        path:
          type: string
          title: Path
          description: File path within the repository
        ref:
          type: string
          title: Ref
          description: Branch, tag, or commit SHA
          default: HEAD
        start_line:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Start Line
          description: 1-based start line
        end_line:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: End Line
          description: 1-based end line (inclusive)
      type: object
      required:
        - repository
        - path
      title: GitHubReadRequest
    GitHubSearchRequest:
      properties:
        query:
          type: string
          title: Query
          description: Code search query
        repository:
          type: string
          title: Repository
          description: Repository in owner/repo format
        per_page:
          type: integer
          maximum: 100
          minimum: 1
          title: Per Page
          description: Results per page
          default: 30
        page:
          type: integer
          minimum: 1
          title: Page
          description: Page number
          default: 1
      type: object
      required:
        - query
        - repository
      title: GitHubSearchRequest
    GlobalSourceSubscribeRequest:
      properties:
        url:
          type: string
          title: Url
          description: >-
            URL of the source (GitHub repo, docs URL, arXiv URL/ID, or
            HuggingFace dataset URL)
        source_type:
          anyOf:
            - type: string
              enum:
                - repository
                - documentation
                - research_paper
                - huggingface_dataset
            - type: 'null'
          title: Source Type
          description: Source type. Auto-detected from URL if not provided.
        ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Ref
          description: Git ref for repositories (branch, tag, or commit SHA)
      type: object
      required:
        - url
      title: GlobalSourceSubscribeRequest
      description: Request model for subscribing to a global source
    GlobalSourceSubscribeResponse:
      properties:
        action:
          type: string
          title: Action
          description: >-
            Action taken: instant_access | wait_for_indexing | not_indexed |
            use_private | indexing_started
        message:
          type: string
          title: Message
          description: Human-readable description of the action
        global_source_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Global Source Id
          description: Canonical ID of the global source
        namespace:
          anyOf:
            - type: string
            - type: 'null'
          title: Namespace
          description: TurboPuffer namespace for the source
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: Current status of the global source
        local_reference_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Local Reference Id
          description: ID of the created local reference (project/data_source)
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Name
          description: Display name of the source
      type: object
      required:
        - action
        - message
      title: GlobalSourceSubscribeResponse
      description: Response model for global source subscription
    GoogleDriveInstallRequest:
      properties:
        redirect_uri:
          anyOf:
            - type: string
            - type: 'null'
          title: Redirect Uri
          description: >-
            Optional OAuth redirect URI override. Defaults to the backend
            callback URL.
        scopes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Scopes
          description: Optional scope override. Defaults to readonly Drive scopes.
      type: object
      title: GoogleDriveInstallRequest
    GoogleDriveOAuthCallbackRequest:
      properties:
        code:
          type: string
          title: Code
          description: Authorization code from Google
        redirect_uri:
          anyOf:
            - type: string
            - type: 'null'
          title: Redirect Uri
          description: Redirect URI used in the authorization request
      type: object
      required:
        - code
      title: GoogleDriveOAuthCallbackRequest
    GrepRequest:
      properties:
        pattern:
          type: string
          title: Pattern
          description: Regex pattern
        path:
          type: string
          title: Path
          description: Path prefix filter
          default: ''
        case_sensitive:
          type: boolean
          title: Case Sensitive
          default: false
        whole_word:
          type: boolean
          title: Whole Word
          default: false
        fixed_string:
          type: boolean
          title: Fixed String
          default: false
        max_total_matches:
          type: integer
          maximum: 10000
          minimum: 1
          title: Max Total Matches
          default: 100
        max_matches_per_file:
          type: integer
          maximum: 100
          minimum: 1
          title: Max Matches Per File
          default: 10
        context_lines:
          type: integer
          maximum: 10
          minimum: 0
          title: Context Lines
          default: 3
        lines_before:
          anyOf:
            - type: integer
            - type: 'null'
          title: Lines Before
        lines_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Lines After
        output_mode:
          type: string
          title: Output Mode
          description: content|files_with_matches|count
          default: content
        multiline_content:
          type: boolean
          title: Multiline Content
          default: false
      type: object
      required:
        - pattern
      title: GrepRequest
    GrepRequestBody:
      properties:
        pattern:
          type: string
          title: Pattern
          description: Regex pattern
        path:
          type: string
          title: Path
          description: Path prefix filter
          default: ''
        case_sensitive:
          type: boolean
          title: Case Sensitive
          default: false
        whole_word:
          type: boolean
          title: Whole Word
          default: false
        fixed_string:
          type: boolean
          title: Fixed String
          default: false
        max_total_matches:
          type: integer
          maximum: 10000
          minimum: 1
          title: Max Total Matches
          default: 100
        max_matches_per_file:
          type: integer
          maximum: 100
          minimum: 1
          title: Max Matches Per File
          default: 10
        context_lines:
          type: integer
          maximum: 10
          minimum: 0
          title: Context Lines
          default: 3
        lines_before:
          anyOf:
            - type: integer
            - type: 'null'
          title: Lines Before
        lines_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Lines After
        highlight:
          type: boolean
          title: Highlight
          default: false
        include_line_numbers:
          type: boolean
          title: Include Line Numbers
          default: true
        output_mode:
          type: string
          title: Output Mode
          description: content|files_with_matches|count
          default: content
        multiline_content:
          type: boolean
          title: Multiline Content
          default: false
      type: object
      required:
        - pattern
      title: GrepRequestBody
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ImportRequest:
      properties:
        manifest:
          additionalProperties: true
          type: object
          title: Manifest
          description: The export manifest JSON
        skip_private_repos:
          type: boolean
          title: Skip Private Repos
          default: false
        skip_contexts:
          type: boolean
          title: Skip Contexts
          default: false
      type: object
      required:
        - manifest
      title: ImportRequest
    IndexRequest:
      properties:
        url:
          type: string
          title: Url
          description: Documentation URL to index.
        force_refresh:
          type: boolean
          title: Force Refresh
          default: false
      type: object
      required:
        - url
      title: IndexRequest
    IndexedResource-Output:
      properties:
        identifier:
          type: string
          title: Identifier
          description: Repository (owner/repo) or documentation URL/ID
        resource_type:
          type: string
          title: Resource Type
          description: 'Type: ''repository'' or ''documentation'''
        purpose:
          type: string
          title: Purpose
          description: Why this resource was used/referenced
        indexed_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Indexed At
          description: When it was indexed
      type: object
      required:
        - identifier
        - resource_type
        - purpose
      title: IndexedResource
      description: Represents a NIA resource (repository or documentation) with context.
    LineageInput:
      properties:
        source_ids:
          items:
            type: string
          type: array
          title: Source Ids
          description: Source identifiers (e.g., 'repo:owner/repo', 'doc:name')
        confidence:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Confidence
          description: Confidence score 0-1
        derived_from:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Derived From
          description: Parent context IDs if derived
        tool_calls:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tool Calls
          description: Tools used to create this artifact
        model_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Version
          description: Model version that created this
      type: object
      title: LineageInput
      description: Input model for lineage tracking.
    LineageMetadata:
      properties:
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When this artifact was created
        source_ids:
          items:
            type: string
          type: array
          title: Source Ids
          description: Source identifiers (e.g., 'repo:owner/repo', 'doc:name')
        confidence:
          anyOf:
            - type: number
            - type: 'null'
          title: Confidence
          description: Confidence score 0-1
        derived_from:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Derived From
          description: Parent context IDs if derived
        tool_calls:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tool Calls
          description: Tools used to create this artifact
        model_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Version
          description: Model version that created this
      type: object
      required:
        - created_at
      title: LineageMetadata
      description: Provenance tracking for content artifacts.
    LocalSourceFilters:
      properties:
        source_subtype:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Subtype
          description: Filter by source subtype (e.g., 'database', 'telegram_export')
        db_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Db Type
          description: >-
            Filter by database type (e.g., 'imessage', 'telegram',
            'safari_history')
        connector_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Connector Type
          description: Filter by connector type (e.g., 'imessage', 'whatsapp', 'contacts')
        conversation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversation Id
          description: Filter to a specific conversation/chat
        contact_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Contact Id
          description: Filter to messages with a specific contact
        sender_role:
          anyOf:
            - type: string
            - type: 'null'
          title: Sender Role
          description: 'Filter by sender role: ''self'' or ''contact'''
        time_after:
          anyOf:
            - type: string
            - type: 'null'
          title: Time After
          description: Only return results with timestamp after this ISO datetime
        time_before:
          anyOf:
            - type: string
            - type: 'null'
          title: Time Before
          description: Only return results with timestamp before this ISO datetime
      type: object
      title: LocalSourceFilters
      description: Filters for local/personal source retrieval (messages, contacts, etc.).
    LoginKeyRequest:
      properties:
        email:
          type: string
          title: Email
        password:
          type: string
          title: Password
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
          description: Org to scope the new key to (must be a member)
        idempotency_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Idempotency Key
      type: object
      required:
        - email
        - password
      title: LoginKeyRequest
    LoginKeyResponse:
      properties:
        api_key:
          type: string
          title: Api Key
        api_key_id:
          type: string
          title: Api Key Id
        user_id:
          type: string
          title: User Id
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
      type: object
      required:
        - api_key
        - api_key_id
        - user_id
      title: LoginKeyResponse
    LoginRequest:
      properties:
        email:
          type: string
          title: Email
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
          description: Org to scope the new key to (must be a member)
      type: object
      required:
        - email
      title: LoginRequest
    LoginResponse:
      properties:
        message:
          type: string
          title: Message
          default: verification code sent
      type: object
      title: LoginResponse
    LoginVerifyRequest:
      properties:
        email:
          type: string
          title: Email
        code:
          type: string
          maxLength: 6
          minLength: 6
          title: Code
          description: 6-digit verification code from email
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
          description: Org to scope the new key to (must be a member)
      type: object
      required:
        - email
        - code
      title: LoginVerifyRequest
    LoginVerifyResponse:
      properties:
        api_key:
          type: string
          title: Api Key
          description: >-
            Your new nk_ API key — store it securely, it cannot be retrieved
            again
        api_key_id:
          type: string
          title: Api Key Id
        user_id:
          type: string
          title: User Id
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
      type: object
      required:
        - api_key
        - api_key_id
        - user_id
      title: LoginVerifyResponse
    MappingItem:
      properties:
        name:
          type: string
          title: Name
        registry:
          type: string
          title: Registry
        docs_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Docs Url
        mapping_source:
          type: string
          title: Mapping Source
        confidence:
          type: number
          title: Confidence
      type: object
      required:
        - name
        - registry
        - docs_url
        - mapping_source
        - confidence
      title: MappingItem
    MkdirBody:
      properties:
        path:
          type: string
          title: Path
      type: object
      required:
        - path
      title: MkdirBody
    MoveBody:
      properties:
        old_path:
          type: string
          title: Old Path
        new_path:
          type: string
          title: New Path
      type: object
      required:
        - old_path
        - new_path
      title: MoveBody
    NiaReferences-Output:
      properties:
        indexed_resources:
          items:
            $ref: '#/components/schemas/IndexedResource-Output'
          type: array
          title: Indexed Resources
        search_queries:
          items:
            $ref: '#/components/schemas/SearchQuery-Output'
          type: array
          title: Search Queries
        session_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Summary
      type: object
      title: NiaReferences
      description: Structured tracking of NIA resources used during conversation.
    OracleResearchRequest:
      properties:
        query:
          type: string
          title: Query
          description: Research question to investigate
        repositories:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Repositories
          description: Optional list of repository identifiers
        data_sources:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Data Sources
          description: Optional list of documentation source identifiers
        output_format:
          anyOf:
            - type: string
            - type: 'null'
          title: Output Format
          description: Optional output format specification
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: >-
            Model to use: claude-opus-4-7, claude-sonnet-4-5-20250929, or
            claude-sonnet-4-5-1m
      type: object
      required:
        - query
      title: OracleResearchRequest
    OracleSessionChatRequest:
      properties:
        message:
          type: string
          maxLength: 10000
          minLength: 1
          title: Message
          description: User's follow-up question
      type: object
      required:
        - message
      title: OracleSessionChatRequest
      description: Request body for session chat.
    PackageSearchGrepRequest:
      properties:
        registry:
          type: string
          title: Registry
          description: 'Registry: crates_io, golang_proxy, npm, py_pi, or ruby_gems'
        package_name:
          type: string
          title: Package Name
          description: Package name
        pattern:
          type: string
          title: Pattern
          description: Regex pattern to search
        version:
          anyOf:
            - type: string
            - type: 'null'
          title: Version
          description: Package version
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          description: Language filter
        filename_sha256:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename Sha256
          description: File SHA256 filter
        a:
          anyOf:
            - type: integer
            - type: 'null'
          title: A
          description: Lines after match
        b:
          anyOf:
            - type: integer
            - type: 'null'
          title: B
          description: Lines before match
        c:
          anyOf:
            - type: integer
            - type: 'null'
          title: C
          description: Lines before and after match
        head_limit:
          anyOf:
            - type: integer
            - type: 'null'
          title: Head Limit
          description: Limit results
        output_mode:
          type: string
          title: Output Mode
          description: 'Output mode: content, files_with_matches, or count'
          default: content
      type: object
      required:
        - registry
        - package_name
        - pattern
      title: PackageSearchGrepRequest
      description: Request model for package grep search
    PackageSearchHybridRequest:
      properties:
        registry:
          type: string
          title: Registry
          description: 'Registry: crates_io, golang_proxy, npm, py_pi, or ruby_gems'
        package_name:
          type: string
          title: Package Name
          description: Package name
        semantic_queries:
          items:
            type: string
          type: array
          title: Semantic Queries
          description: 1-5 semantic queries
        version:
          anyOf:
            - type: string
            - type: 'null'
          title: Version
          description: Package version
        filename_sha256:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename Sha256
          description: File SHA256 filter
        pattern:
          anyOf:
            - type: string
            - type: 'null'
          title: Pattern
          description: Regex pattern filter
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          description: Language filter
      type: object
      required:
        - registry
        - package_name
        - semantic_queries
      title: PackageSearchHybridRequest
      description: Request model for package hybrid search
    PackageSearchReadFileRequest:
      properties:
        registry:
          type: string
          title: Registry
          description: 'Registry: crates_io, golang_proxy, npm, py_pi, or ruby_gems'
        package_name:
          type: string
          title: Package Name
          description: Package name
        filename_sha256:
          type: string
          title: Filename Sha256
          description: File SHA256
        start_line:
          type: integer
          title: Start Line
          description: Start line (1-based)
        end_line:
          type: integer
          title: End Line
          description: End line (1-based)
        version:
          anyOf:
            - type: string
            - type: 'null'
          title: Version
          description: Package version
      type: object
      required:
        - registry
        - package_name
        - filename_sha256
        - start_line
        - end_line
      title: PackageSearchReadFileRequest
      description: Request model for reading package file
    PaginationInfo:
      properties:
        total:
          type: integer
          title: Total
          description: Total number of items
        limit:
          type: integer
          title: Limit
          description: Items per page
        offset:
          type: integer
          title: Offset
          description: Current offset
        has_more:
          type: boolean
          title: Has More
          description: Whether more items exist
      type: object
      required:
        - total
        - limit
        - offset
        - has_more
      title: PaginationInfo
      description: Pagination metadata.
    QuerySearchRequest:
      properties:
        messages:
          items:
            additionalProperties: true
            type: object
          type: array
          minItems: 1
          title: Messages
          description: List of chat messages
        repositories:
          items:
            anyOf:
              - type: string
              - additionalProperties: true
                type: object
          type: array
          title: Repositories
          description: >-
            List of repositories to query. Can be strings (slug, display name)
            or dicts with a 'repository' field.
        data_sources:
          items:
            anyOf:
              - type: string
              - additionalProperties: true
                type: object
          type: array
          title: Data Sources
          description: >-
            List of data sources to query. Can be strings (display_name, URL, or
            source_id) or dicts with 'source_id' or 'identifier' fields
        local_folders:
          items:
            anyOf:
              - type: string
              - additionalProperties: true
                type: object
          type: array
          title: Local Folders
          description: >-
            List of local folders to query. Can be strings (display_name or
            local_folder_id) or dicts with 'local_folder_id' or 'identifier'
            fields. Local folders are private and user-scoped.
        slack_workspaces:
          items:
            type: string
          type: array
          title: Slack Workspaces
          description: List of Slack installation IDs to include in search
        slack_filters:
          anyOf:
            - $ref: '#/components/schemas/SlackSearchFilters'
            - type: 'null'
          description: Filters for Slack message results (channels, users, date range)
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
          description: >-
            Filter local folder results by classification category (e.g.,
            'Work', 'Personal')
        local_source_filters:
          anyOf:
            - $ref: '#/components/schemas/LocalSourceFilters'
            - type: 'null'
          description: Filters for local/personal sources (messages, contacts, etc.)
        source_trust_filter:
          anyOf:
            - $ref: '#/components/schemas/SourceTrustFilter'
            - type: 'null'
          description: Optional trust-aware filtering for curated source results
        search_mode:
          type: string
          title: Search Mode
          description: 'Search mode: ''repositories'', ''sources'', or ''unified'''
          default: unified
        stream:
          type: boolean
          title: Stream
          description: Whether to stream the response
          default: false
        include_sources:
          type: boolean
          title: Include Sources
          description: Whether to include source texts in the response
          default: true
        fast_mode:
          type: boolean
          title: Fast Mode
          description: >-
            Skip LLM processing for faster results (100-500ms vs 2-8s). Set to
            false for deeper analysis.
          default: true
        skip_llm:
          type: boolean
          title: Skip Llm
          description: >-
            Return raw search results without any LLM processing. Returns only
            sources with scores.
          default: false
        reasoning_strategy:
          type: string
          title: Reasoning Strategy
          description: >-
            Retrieval strategy: 'vector' (default similarity search), 'tree'
            (LLM-guided tree navigation for PDFs), or 'hybrid' (both combined)
          default: vector
        max_tokens:
          anyOf:
            - type: integer
              maximum: 100000
              minimum: 100
            - type: 'null'
          title: Max Tokens
          description: Maximum tokens in response. Results truncated when budget reached.
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: >-
            Synthesis model override. Allowed: claude-sonnet-4-5,
            gpt-5.2-2025-12-11, claude-haiku-4-5-20251001
        semantic_cache_threshold:
          type: number
          maximum: 1
          minimum: 0.8
          title: Semantic Cache Threshold
          description: Minimum similarity for semantic cache hit (non-streaming only)
          default: 0.92
        bypass_semantic_cache:
          type: boolean
          title: Bypass Semantic Cache
          description: Skip semantic cache (L2) lookup
          default: false
        include_follow_ups:
          type: boolean
          title: Include Follow Ups
          description: >-
            Generate follow-up questions (adds ~500-1000ms LLM latency).
            Disabled by default for speed.
          default: false
        e2e_session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: E2E Session Id
          description: >-
            Active E2E decrypt session ID. When provided, encrypted local folder
            results are decrypted through the desktop bridge before synthesis.
        mode:
          type: string
          const: query
          title: Mode
          description: Search mode discriminator
          default: query
      type: object
      required:
        - messages
      title: QuerySearchRequest
    ResendCodeResponse:
      properties:
        message:
          type: string
          title: Message
          default: verification code sent
      type: object
      title: ResendCodeResponse
    SearchQuery-Output:
      properties:
        query:
          type: string
          title: Query
          description: The search query that was performed
        query_type:
          type: string
          title: Query Type
          description: 'Type: ''codebase'', ''documentation'', etc.'
        resources_searched:
          items:
            type: string
          type: array
          title: Resources Searched
        key_findings:
          type: string
          title: Key Findings
          description: Brief summary of what was found
        useful_results_count:
          type: integer
          title: Useful Results Count
          default: 0
      type: object
      required:
        - query
        - query_type
        - key_findings
      title: SearchQuery
      description: Represents a search query performed during the conversation.
    SearchScope:
      properties:
        repositories:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Repositories
          description: Repository identifiers to search
        data_sources:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Data Sources
          description: Documentation source IDs to search
      type: object
      title: SearchScope
      description: Scope for searching Nia's indexed sources.
    SignupRequest:
      properties:
        email:
          type: string
          title: Email
          description: User email address
        password:
          anyOf:
            - type: string
              minLength: 8
            - type: 'null'
          title: Password
          description: Optional password for web login (random if omitted)
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
        organization_name:
          type: string
          minLength: 1
          title: Organization Name
          description: Organization name (required — all API keys are org-scoped)
        idempotency_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Idempotency Key
          description: Idempotency key for safe retries
      type: object
      required:
        - email
        - organization_name
      title: SignupRequest
    SignupResponse:
      properties:
        api_key:
          type: string
          title: Api Key
          description: >-
            Read-only API key — verify via POST /v2/auth/verify to unlock full
            access
        api_key_id:
          type: string
          title: Api Key Id
        user_id:
          type: string
          title: User Id
        organization_id:
          type: string
          title: Organization Id
        verified:
          type: boolean
          title: Verified
          description: Whether the account has been verified (always false on signup)
          default: false
      type: object
      required:
        - api_key
        - api_key_id
        - user_id
        - organization_id
      title: SignupResponse
    SlackGrepRequest:
      properties:
        pattern:
          type: string
          minLength: 1
          title: Pattern
          description: Search string for BM25 keyword matching
        channel:
          anyOf:
            - type: string
            - type: 'null'
          title: Channel
          description: Filter by channel name or ID
        limit:
          type: integer
          maximum: 100
          minimum: 1
          title: Limit
          description: Max results
          default: 20
      type: object
      required:
        - pattern
      title: SlackGrepRequest
    SlackInstallRequest:
      properties:
        redirect_uri:
          anyOf:
            - type: string
            - type: 'null'
          title: Redirect Uri
          description: Custom OAuth redirect URI
        scopes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Scopes
          description: Override default bot scopes
      type: object
      title: SlackInstallRequest
      description: Generate an OAuth URL to install Nia's Slack app.
    SlackOAuthCallbackRequest:
      properties:
        code:
          type: string
          title: Code
          description: Authorization code from Slack
        redirect_uri:
          anyOf:
            - type: string
            - type: 'null'
          title: Redirect Uri
          description: Redirect URI used in the authorization request
      type: object
      required:
        - code
      title: SlackOAuthCallbackRequest
      description: Handle the OAuth callback from Slack.
    SlackSearchFilters:
      properties:
        channels:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Channels
          description: Filter by channel names or IDs
        users:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Users
          description: Filter by Slack user names or IDs
        date_from:
          anyOf:
            - type: string
            - type: 'null'
          title: Date From
          description: Oldest message timestamp (ISO 8601)
        date_to:
          anyOf:
            - type: string
            - type: 'null'
          title: Date To
          description: Newest message timestamp (ISO 8601)
        include_threads:
          type: boolean
          title: Include Threads
          description: Include threaded messages in results
          default: true
      type: object
      title: SlackSearchFilters
      description: Filters for Slack message search within query endpoint.
    SlackTokenRequest:
      properties:
        bot_token:
          type: string
          title: Bot Token
          description: Slack bot token (xoxb-...)
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Display name for this workspace
      type: object
      required:
        - bot_token
      title: SlackTokenRequest
      description: 'BYOT: Register an external Slack bot token.'
    Source:
      properties:
        id:
          type: string
          title: Id
          description: Source identifier
        type:
          type: string
          enum:
            - repository
            - documentation
            - research_paper
            - huggingface_dataset
            - local_folder
            - slack
            - google_drive
            - connector
          title: Type
          description: Source type
        identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Identifier
          description: Canonical identifier (repo slug, URL, or folder path)
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Name
          description: Human-readable name
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: Indexing status
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
          description: Creation timestamp (ISO)
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated At
          description: Last update timestamp (ISO)
        category_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Category Id
          description: Category assignment
        is_global:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Global
          description: Whether the source is global/shared
        global_source_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Global Source Id
          description: Global source ID if applicable
        global_namespace:
          anyOf:
            - type: string
            - type: 'null'
          title: Global Namespace
          description: Global namespace if applicable
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Type-specific metadata
        curation:
          anyOf:
            - $ref: '#/components/schemas/SourceCurationSummary'
            - type: 'null'
          description: Trust signals and curated guidance summary
      type: object
      required:
        - id
        - type
      title: Source
      description: Unified source representation.
    SourceAnnotation:
      properties:
        id:
          type: string
          title: Id
          description: Annotation identifier
        kind:
          type: string
          enum:
            - note
            - tip
            - warning
            - gotcha
          title: Kind
          description: Annotation category
          default: note
        content:
          type: string
          title: Content
          description: Annotation text
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
          description: Creation timestamp (ISO)
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated At
          description: Last update timestamp (ISO)
      type: object
      required:
        - id
        - content
      title: SourceAnnotation
      description: A saved note attached to a source.
    SourceAnnotationCreateRequest:
      properties:
        kind:
          type: string
          enum:
            - note
            - tip
            - warning
            - gotcha
          title: Kind
          description: Annotation category
          default: note
        content:
          type: string
          minLength: 1
          title: Content
          description: Annotation body
      type: object
      required:
        - content
      title: SourceAnnotationCreateRequest
    SourceAnnotationUpdateRequest:
      properties:
        kind:
          anyOf:
            - type: string
              enum:
                - note
                - tip
                - warning
                - gotcha
            - type: 'null'
          title: Kind
          description: Updated annotation category
        content:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Content
          description: Updated annotation body
      type: object
      title: SourceAnnotationUpdateRequest
    SourceContentResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether retrieval succeeded
        content:
          type: string
          title: Content
          description: Source content
          default: ''
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Content metadata
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if failed
      type: object
      required:
        - success
      title: SourceContentResponse
      description: Response for source content retrieval.
    SourceCreateRequest:
      properties:
        type:
          type: string
          enum:
            - repository
            - documentation
            - research_paper
            - huggingface_dataset
            - local_folder
            - slack
            - google_drive
            - connector
          title: Type
        repository:
          anyOf:
            - type: string
            - type: 'null'
          title: Repository
        branch:
          anyOf:
            - type: string
            - type: 'null'
          title: Branch
        ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Ref
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        url_patterns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Url Patterns
        exclude_patterns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Patterns
        project_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Id
        max_age:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Age
        formats:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Formats
        only_main_content:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Only Main Content
        limit:
          anyOf:
            - type: integer
            - type: 'null'
          title: Limit
        max_depth:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Depth
        crawl_entire_domain:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Crawl Entire Domain
        wait_for:
          anyOf:
            - type: integer
            - type: 'null'
          title: Wait For
        include_screenshot:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Include Screenshot
        check_llms_txt:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Check Llms Txt
        llms_txt_strategy:
          anyOf:
            - type: string
            - type: 'null'
          title: Llms Txt Strategy
        add_as_global_source:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Add As Global Source
          default: true
        is_pdf:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Pdf
        is_spreadsheet:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Spreadsheet
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Name
        gcs_path:
          anyOf:
            - type: string
            - type: 'null'
          title: Gcs Path
        focus_instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: Focus Instructions
        extract_branding:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Extract Branding
        extract_images:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Extract Images
        config:
          anyOf:
            - type: string
            - type: 'null'
          title: Config
        folder_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Folder Name
        folder_path:
          anyOf:
            - type: string
            - type: 'null'
          title: Folder Path
        files:
          anyOf:
            - items:
                $ref: '#/components/schemas/FileItem'
              type: array
            - type: 'null'
          title: Files
        database:
          anyOf:
            - $ref: '#/components/schemas/DatabaseFileItem'
            - type: 'null'
        slack_installation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Slack Installation Id
        google_drive_installation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Google Drive Installation Id
        google_drive_file_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Google Drive File Ids
        google_drive_folder_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Google Drive Folder Ids
      type: object
      required:
        - type
      title: SourceCreateRequest
    SourceCuratedOverlay:
      properties:
        kind:
          type: string
          enum:
            - custom
            - nia_verified
          title: Kind
          description: Overlay provenance
          default: custom
        summary:
          type: string
          title: Summary
          description: Short high-confidence summary for the source
        guidance:
          anyOf:
            - type: string
            - type: 'null'
          title: Guidance
          description: Longer coding-agent guidance or caveats
        recommended_queries:
          items:
            type: string
          type: array
          title: Recommended Queries
          description: Suggested follow-up prompts for agents
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated At
          description: Last overlay update timestamp (ISO)
      type: object
      required:
        - summary
      title: SourceCuratedOverlay
      description: Structured high-confidence guidance layered on top of a source.
    SourceCurationResponse:
      properties:
        source_id:
          type: string
          title: Source Id
          description: Source identifier
        source_type:
          type: string
          enum:
            - repository
            - documentation
            - research_paper
            - huggingface_dataset
            - local_folder
            - slack
            - google_drive
            - connector
          title: Source Type
          description: Source type
        trust_signals:
          $ref: '#/components/schemas/SourceTrustSignals'
          description: Derived trust signals
        overlay:
          anyOf:
            - $ref: '#/components/schemas/SourceCuratedOverlay'
            - type: 'null'
          description: Curated overlay if present
        annotations:
          items:
            $ref: '#/components/schemas/SourceAnnotation'
          type: array
          title: Annotations
          description: Saved annotations for the source
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
          description: Curation record creation timestamp (ISO)
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated At
          description: Curation record update timestamp (ISO)
      type: object
      required:
        - source_id
        - source_type
      title: SourceCurationResponse
      description: Full curation state for a source.
    SourceCurationSummary:
      properties:
        trust_signals:
          $ref: '#/components/schemas/SourceTrustSignals'
          description: Derived trust signals
        overlay_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Overlay Summary
          description: Short overlay summary if one exists
        recommended_queries:
          items:
            type: string
          type: array
          title: Recommended Queries
          description: Suggested prompts from the overlay
      type: object
      title: SourceCurationSummary
      description: Compact curation info embedded into source responses.
    SourceCurationUpdateRequest:
      properties:
        trust_level:
          anyOf:
            - type: string
              enum:
                - low
                - medium
                - high
            - type: 'null'
          title: Trust Level
          description: Trust preference for this source
        overlay_kind:
          anyOf:
            - type: string
              enum:
                - custom
                - nia_verified
            - type: 'null'
          title: Overlay Kind
          description: Overlay provenance
        overlay_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Overlay Summary
          description: Short curated source summary
        overlay_guidance:
          anyOf:
            - type: string
            - type: 'null'
          title: Overlay Guidance
          description: Longer guidance for coding agents
        recommended_queries:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Recommended Queries
          description: Suggested prompts for this source
        clear_overlay:
          type: boolean
          title: Clear Overlay
          description: Remove any existing curated overlay
          default: false
      type: object
      title: SourceCurationUpdateRequest
    SourceDeleteResponse:
      properties:
        id:
          type: string
          title: Id
          description: Source ID
        status:
          type: string
          title: Status
          description: Deletion status
      type: object
      required:
        - id
        - status
      title: SourceDeleteResponse
      description: Response for deleting a source.
    SourceFeedbackRequest:
      properties:
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Message Id
        chunk_id:
          type: string
          title: Chunk Id
        content_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Hash
        signal:
          type: string
          enum:
            - helpful
            - irrelevant
            - partially_relevant
          title: Signal
        retrieval_log_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Retrieval Log Id
      type: object
      required:
        - chunk_id
        - signal
      title: SourceFeedbackRequest
    SourceInteractionRequest:
      properties:
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Message Id
        chunk_id:
          type: string
          title: Chunk Id
        content_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Hash
        retrieval_log_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Retrieval Log Id
        action:
          type: string
          enum:
            - expanded
            - copied
            - navigated
            - collapsed
            - dwelled
          title: Action
        position_shown:
          anyOf:
            - type: integer
            - type: 'null'
          title: Position Shown
        dwell_time_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Dwell Time Ms
      type: object
      required:
        - chunk_id
        - action
      title: SourceInteractionRequest
    SourceListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/Source'
          type: array
          title: Items
          description: List of sources
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
          description: Pagination metadata
      type: object
      required:
        - pagination
      title: SourceListResponse
      description: Response for listing sources.
    SourceResolveResponse:
      properties:
        id:
          type: string
          title: Id
          description: Resolved source ID
        type:
          type: string
          enum:
            - repository
            - documentation
            - research_paper
            - huggingface_dataset
            - local_folder
            - slack
            - google_drive
            - connector
          title: Type
          description: Resolved source type
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Name
          description: Display name
        identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Identifier
          description: Canonical identifier
      type: object
      required:
        - id
        - type
      title: SourceResolveResponse
      description: Response for resolving a source identifier.
    SourceTrustFilter:
      properties:
        minimum_trust_tier:
          anyOf:
            - type: string
              enum:
                - low
                - medium
                - high
                - verified
            - type: 'null'
          title: Minimum Trust Tier
          description: Only include sources at or above this effective trust tier
        verified_only:
          type: boolean
          title: Verified Only
          description: Only include Nia-verified sources
          default: false
        require_overlay:
          type: boolean
          title: Require Overlay
          description: Only include sources with curated overlays
          default: false
      type: object
      title: SourceTrustFilter
      description: Filtering preferences for trust-aware retrieval.
    SourceTrustSignals:
      properties:
        trust_level:
          type: string
          enum:
            - low
            - medium
            - high
          title: Trust Level
          description: User or team trust preference for the source
          default: medium
        trust_tier:
          type: string
          enum:
            - low
            - medium
            - high
            - verified
          title: Trust Tier
          description: Effective trust tier after derived verified/global signals
          default: medium
        scope:
          type: string
          enum:
            - private
            - organization
            - global
          title: Scope
          description: Ownership scope of the source
          default: private
        is_global:
          type: boolean
          title: Is Global
          description: Whether the source references a shared global source
          default: false
        is_verified:
          type: boolean
          title: Is Verified
          description: Whether the source has a Nia-verified overlay
          default: false
        overlay_available:
          type: boolean
          title: Overlay Available
          description: Whether a curated overlay is attached
          default: false
        annotation_count:
          type: integer
          title: Annotation Count
          description: Number of saved annotations for this source
          default: 0
      type: object
      title: SourceTrustSignals
      description: Trust and curation signals attached to a source.
    SourceTypeSummary:
      properties:
        count:
          type: integer
          title: Count
          description: Total number of sources of this type
          default: 0
        names:
          items:
            type: string
          type: array
          title: Names
          description: Names of most recent sources (up to 5)
      type: object
      title: SourceTypeSummary
    SourceUpdateRequest:
      properties:
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Name
        category_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Category Id
      type: object
      title: SourceUpdateRequest
    SourceUploadUrlRequest:
      properties:
        filename:
          type: string
          minLength: 1
          title: Filename
          description: Original filename (used for storage object naming)
        content_type:
          type: string
          title: Content Type
          description: MIME type for upload (PDF, CSV, TSV, XLS, XLSX)
          default: application/pdf
      type: object
      required:
        - filename
      title: SourceUploadUrlRequest
    SourceUploadUrlResponse:
      properties:
        upload_url:
          type: string
          title: Upload Url
          description: Signed URL for direct upload (HTTP PUT)
        gcs_path:
          type: string
          title: Gcs Path
          description: GCS path to pass to create-source payload
        expires_in_seconds:
          type: integer
          title: Expires In Seconds
          description: Signed URL expiration in seconds
      type: object
      required:
        - upload_url
        - gcs_path
        - expires_in_seconds
      title: SourceUploadUrlResponse
    SourcesSummaryResponse:
      properties:
        repositories:
          $ref: '#/components/schemas/SourceTypeSummary'
        documentation:
          $ref: '#/components/schemas/SourceTypeSummary'
        research_papers:
          $ref: '#/components/schemas/SourceTypeSummary'
        huggingface_datasets:
          $ref: '#/components/schemas/SourceTypeSummary'
        local_folders:
          $ref: '#/components/schemas/SourceTypeSummary'
        slack:
          $ref: '#/components/schemas/SourceTypeSummary'
        google_drive:
          $ref: '#/components/schemas/SourceTypeSummary'
        x:
          $ref: '#/components/schemas/SourceTypeSummary'
      type: object
      required:
        - repositories
        - documentation
        - research_papers
        - huggingface_datasets
        - local_folders
        - slack
        - google_drive
        - x
      title: SourcesSummaryResponse
    SubscriptionResultItem:
      properties:
        name:
          type: string
          title: Name
        action:
          type: string
          title: Action
        docs_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Docs Url
        global_source_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Global Source Id
        namespace:
          anyOf:
            - type: string
            - type: 'null'
          title: Namespace
        message:
          type: string
          title: Message
      type: object
      required:
        - name
        - action
        - docs_url
        - global_source_id
        - namespace
        - message
      title: SubscriptionResultItem
    SubscriptionResults:
      properties:
        instant_access:
          items:
            $ref: '#/components/schemas/SubscriptionResultItem'
          type: array
          title: Instant Access
        wait_for_indexing:
          items:
            $ref: '#/components/schemas/SubscriptionResultItem'
          type: array
          title: Wait For Indexing
        started_indexing:
          items:
            $ref: '#/components/schemas/SubscriptionResultItem'
          type: array
          title: Started Indexing
        not_found:
          items:
            $ref: '#/components/schemas/SubscriptionResultItem'
          type: array
          title: Not Found
        errors:
          items:
            $ref: '#/components/schemas/SubscriptionResultItem'
          type: array
          title: Errors
        skipped:
          items:
            $ref: '#/components/schemas/SubscriptionResultItem'
          type: array
          title: Skipped
      type: object
      required:
        - instant_access
        - wait_for_indexing
        - started_indexing
        - not_found
        - errors
        - skipped
      title: SubscriptionResults
    SubscriptionSummary:
      properties:
        instant_access:
          type: integer
          title: Instant Access
        wait_for_indexing:
          type: integer
          title: Wait For Indexing
        started_indexing:
          type: integer
          title: Started Indexing
        not_found:
          type: integer
          title: Not Found
        errors:
          type: integer
          title: Errors
        skipped:
          type: integer
          title: Skipped
      type: object
      required:
        - instant_access
        - wait_for_indexing
        - started_indexing
        - not_found
        - errors
        - skipped
      title: SubscriptionSummary
    TelemetryEvent:
      properties:
        seq:
          type: integer
          title: Seq
        ts:
          type: string
          title: Ts
        type:
          type: string
          title: Type
          default: command
        raw:
          type: string
          title: Raw
        name:
          type: string
          title: Name
        args:
          items: {}
          type: array
          title: Args
          default: []
        cwd:
          type: string
          title: Cwd
          default: ''
        exit_code:
          type: integer
          title: Exit Code
          default: 0
        stdout_bytes:
          type: integer
          title: Stdout Bytes
          default: 0
        stderr_bytes:
          type: integer
          title: Stderr Bytes
          default: 0
        duration_ms:
          type: integer
          title: Duration Ms
          default: 0
        pattern:
          anyOf:
            - type: string
            - type: 'null'
          title: Pattern
        paths:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Paths
        flags:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Flags
        result_files:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Result Files
      type: object
      required:
        - seq
        - ts
        - raw
        - name
      title: TelemetryEvent
    TelemetryPayload:
      properties:
        session_id:
          type: string
          title: Session Id
        namespace:
          type: string
          title: Namespace
        domain:
          type: string
          title: Domain
        url:
          type: string
          title: Url
        mode:
          type: string
          title: Mode
        started_at:
          type: string
          title: Started At
        ended_at:
          type: string
          title: Ended At
        file_count:
          type: integer
          title: File Count
          default: 0
        events:
          items:
            $ref: '#/components/schemas/TelemetryEvent'
          type: array
          maxItems: 1000
          title: Events
      type: object
      required:
        - session_id
        - namespace
        - domain
        - url
        - mode
        - started_at
        - ended_at
      title: TelemetryPayload
    TracerRequest:
      properties:
        query:
          type: string
          maxLength: 10000
          minLength: 1
          title: Query
          description: Research question
        repositories:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Repositories
          description: Repositories in owner/repo format
        context:
          anyOf:
            - type: string
              maxLength: 5000
            - type: 'null'
          title: Context
          description: Additional context
        model:
          anyOf:
            - type: string
              enum:
                - claude-haiku-4-5-20251001
                - claude-opus-4-7
            - type: 'null'
          title: Model
          description: >-
            Optional model override (claude-haiku-4-5-20251001, claude-opus-4-7,
            claude-opus-4-7). Must match mode when both are provided.
        mode:
          anyOf:
            - type: string
              enum:
                - tracer-fast
                - tracer-deep
            - type: 'null'
          title: Mode
          description: >-
            Tracer mode: tracer-fast (Haiku) or tracer-deep (Opus). Defaults to
            tracer-deep. When mode and model are both provided, they must agree.
      type: object
      required:
        - query
      title: TracerRequest
    UniversalSearchRequestWithMode:
      properties:
        query:
          type: string
          title: Query
          description: Natural language search query
        top_k:
          type: integer
          maximum: 100
          minimum: 1
          title: Top K
          description: Total number of results
          default: 20
        include_repos:
          type: boolean
          title: Include Repos
          description: Include repository sources
          default: true
        include_docs:
          type: boolean
          title: Include Docs
          description: Include documentation sources
          default: true
        include_huggingface_datasets:
          type: boolean
          title: Include Huggingface Datasets
          description: >-
            Include HuggingFace dataset sources (excluded by default to prevent
            search pollution)
          default: false
        alpha:
          type: number
          maximum: 1
          minimum: 0
          title: Alpha
          description: Weight for vector search (0.7 = 70% vector)
          default: 0.7
        compress_output:
          type: boolean
          title: Compress Output
          description: Use AI to compress results
          default: false
        max_sources:
          type: integer
          maximum: 30
          minimum: 1
          title: Max Sources
          description: Max source namespaces to deep search
          default: 5
        sources_for_answer:
          type: integer
          maximum: 30
          minimum: 1
          title: Sources For Answer
          description: Number of results to use for AI answer
          default: 10
        bypass_cache:
          type: boolean
          title: Bypass Cache
          description: Skip cache and force fresh search results
          default: false
        max_tokens:
          anyOf:
            - type: integer
              maximum: 100000
              minimum: 100
            - type: 'null'
          title: Max Tokens
          description: Maximum tokens in response. Results truncated when budget reached.
        boost_source_types:
          additionalProperties:
            type: number
          type: object
          title: Boost Source Types
          description: Source type boosts (override to customize or set {} to disable)
          default:
            repository: 1.2
            documentation: 1
            research_paper: 0.9
            huggingface_dataset: 0.85
        boost_languages:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Boost Languages
          description: Programming languages to boost (e.g., ['python', 'typescript'])
        language_boost_factor:
          type: number
          maximum: 5
          minimum: 1
          title: Language Boost Factor
          description: Boost multiplier for preferred languages
          default: 1.5
        use_native_boosting:
          type: boolean
          title: Use Native Boosting
          description: Use TurboPuffer FTS v2 native Sum/Product boosting
          default: true
        semantic_cache_threshold:
          type: number
          maximum: 1
          minimum: 0.8
          title: Semantic Cache Threshold
          description: Minimum similarity for semantic cache hit (0.8-1.0)
          default: 0.92
        bypass_semantic_cache:
          type: boolean
          title: Bypass Semantic Cache
          description: Skip semantic cache (L2) lookup
          default: false
        expand_symbols:
          type: boolean
          title: Expand Symbols
          description: >-
            Extract function/class names from results and search for usages
            (cAST-inspired)
          default: false
        mode:
          type: string
          const: universal
          title: Mode
          description: Search mode discriminator
          default: universal
      type: object
      required:
        - query
      title: UniversalSearchRequestWithMode
    UsageSummaryResponse:
      properties:
        user_id:
          type: string
          title: User Id
          description: User identifier
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
          description: Organization identifier (if applicable)
        subscription_tier:
          type: string
          title: Subscription Tier
          description: Current subscription tier
          default: free
        billing_period_start:
          type: string
          format: date-time
          title: Billing Period Start
          description: Start of current billing period
        billing_period_end:
          type: string
          format: date-time
          title: Billing Period End
          description: End of current billing period
        usage:
          additionalProperties:
            $ref: '#/components/schemas/UsageSummaryUsageEntry'
          type: object
          title: Usage
          description: Usage breakdown by operation type
      type: object
      required:
        - user_id
        - billing_period_start
        - billing_period_end
      title: UsageSummaryResponse
      description: Response for usage summary.
    UsageSummaryUsageEntry:
      properties:
        used:
          type: integer
          title: Used
          description: Number of operations used this period
          default: 0
        limit:
          type: integer
          title: Limit
          description: Maximum allowed operations (0 if unlimited)
          default: 0
        unlimited:
          type: boolean
          title: Unlimited
          description: Whether this operation type is unlimited
          default: false
      type: object
      title: UsageSummaryUsageEntry
      description: Usage breakdown for a single operation type.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    VerifyRequest:
      properties:
        code:
          type: string
          maxLength: 6
          minLength: 6
          title: Code
          description: 6-digit verification code from email
      type: object
      required:
        - code
      title: VerifyRequest
    VerifyResponse:
      properties:
        verified:
          type: boolean
          title: Verified
          default: true
      type: object
      title: VerifyResponse
    WebSearchRequestWithMode:
      properties:
        query:
          type: string
          title: Query
          description: Search query
        num_results:
          type: integer
          maximum: 10
          minimum: 1
          title: Num Results
          description: Number of results
          default: 5
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
          description: >-
            Filter by category: github, company, research, news, tweet, pdf,
            blog
        days_back:
          anyOf:
            - type: integer
            - type: 'null'
          title: Days Back
          description: Only show results from last N days
        find_similar_to:
          anyOf:
            - type: string
            - type: 'null'
          title: Find Similar To
          description: URL to find similar content to
        mode:
          type: string
          const: web
          title: Mode
          description: Search mode discriminator
          default: web
      type: object
      required:
        - query
      title: WebSearchRequestWithMode
    WriteBatchBody:
      properties:
        files:
          items:
            $ref: '#/components/schemas/WriteFileBody'
          type: array
          title: Files
      type: object
      required:
        - files
      title: WriteBatchBody
    WriteFileBody:
      properties:
        path:
          type: string
          title: Path
        body:
          type: string
          title: Body
        encoding:
          type: string
          title: Encoding
          default: utf8
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
        headers:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Headers
      type: object
      required:
        - path
        - body
      title: WriteFileBody
    routes__v2__categories__CategoryCreate:
      properties:
        name:
          type: string
          maxLength: 50
          minLength: 1
          title: Name
          description: Category name
        color:
          anyOf:
            - type: string
              maxLength: 7
            - type: 'null'
          title: Color
          description: 'Hex color (e.g., #FF5733)'
        order:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Order
          description: Display order
      type: object
      required:
        - name
      title: CategoryCreate
    routes__v2__categories__CategoryUpdate:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 50
              minLength: 1
            - type: 'null'
          title: Name
          description: Category name
        color:
          anyOf:
            - type: string
              maxLength: 7
            - type: 'null'
          title: Color
          description: 'Hex color (e.g., #FF5733)'
        order:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Order
          description: Display order
      type: object
      title: CategoryUpdate
    routes__v2__contexts__EditedFile:
      properties:
        file_path:
          type: string
          title: File Path
          description: Path to the file
        operation:
          type: string
          title: Operation
          description: 'Type: ''created'', ''modified'', ''deleted'''
        changes_description:
          type: string
          title: Changes Description
          description: Brief description of changes
        key_changes:
          items:
            type: string
          type: array
          title: Key Changes
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          description: Programming language of the file
      type: object
      required:
        - file_path
        - operation
        - changes_description
      title: EditedFile
      description: Represents a file that was modified during the conversation.
    routes__v2__contexts__IndexedResource:
      properties:
        identifier:
          type: string
          title: Identifier
          description: Repository (owner/repo) or documentation URL/ID
        resource_type:
          type: string
          title: Resource Type
          description: 'Type: ''repository'' or ''documentation'''
        purpose:
          type: string
          title: Purpose
          description: Why this resource was used/referenced
        indexed_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Indexed At
          description: When it was indexed
      type: object
      required:
        - identifier
        - resource_type
        - purpose
      title: IndexedResource
      description: Represents a NIA resource (repository or documentation) with context.
    routes__v2__contexts__NiaReferences-Input:
      properties:
        indexed_resources:
          items:
            $ref: '#/components/schemas/routes__v2__contexts__IndexedResource'
          type: array
          title: Indexed Resources
        search_queries:
          items:
            $ref: '#/components/schemas/routes__v2__contexts__SearchQuery'
          type: array
          title: Search Queries
        session_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Summary
      type: object
      title: NiaReferences
      description: Structured tracking of NIA resources used during conversation.
    routes__v2__contexts__SearchQuery:
      properties:
        query:
          type: string
          title: Query
          description: The search query that was performed
        query_type:
          type: string
          title: Query Type
          description: 'Type: ''codebase'', ''documentation'', etc.'
        resources_searched:
          items:
            type: string
          type: array
          title: Resources Searched
        key_findings:
          type: string
          title: Key Findings
          description: Brief summary of what was found
        useful_results_count:
          type: integer
          title: Useful Results Count
          default: 0
      type: object
      required:
        - query
        - query_type
        - key_findings
      title: SearchQuery
      description: Represents a search query performed during the conversation.
    routes__v2__dependencies__SubscribeResponse:
      properties:
        manifest_type:
          type: string
          title: Manifest Type
        total_dependencies:
          type: integer
          title: Total Dependencies
        results:
          $ref: '#/components/schemas/SubscriptionResults'
        summary:
          $ref: '#/components/schemas/SubscriptionSummary'
      type: object
      required:
        - manifest_type
        - total_dependencies
        - results
        - summary
      title: SubscribeResponse
    routes__v2__google_drive__GoogleDriveIndexRequest:
      properties:
        file_ids:
          items:
            type: string
          type: array
          title: File Ids
          description: Drive file IDs to index
        folder_ids:
          items:
            type: string
          type: array
          title: Folder Ids
          description: Drive folder IDs to index
        display_name:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          title: Display Name
          description: Optional custom display name for the indexed Drive source
      type: object
      title: GoogleDriveIndexRequest
    routes__v2__google_drive__GoogleDriveSelectionRequest:
      properties:
        item_ids:
          items:
            type: string
          type: array
          minItems: 1
          title: Item Ids
          description: Drive file or folder IDs to index
        display_name:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          title: Display Name
          description: Optional custom display name for the Drive source
      type: object
      required:
        - item_ids
      title: GoogleDriveSelectionRequest
    routes__v2__google_drive__GoogleDriveSyncRequest:
      properties:
        force_full:
          type: boolean
          title: Force Full
          description: Force a full rebuild instead of incremental sync
          default: false
        scope_ids:
          items:
            type: string
          type: array
          title: Scope Ids
          description: Optional sync scope IDs to limit the sync run
      type: object
      title: GoogleDriveSyncRequest
    routes__v2__slack__SlackChannelsConfigRequest:
      properties:
        mode:
          type: string
          title: Mode
          description: '''all'' to index all channels, ''selected'' to pick specific ones'
          default: all
        include_channels:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Include Channels
          description: Channel IDs to include (when mode='selected')
        exclude_channels:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Channels
          description: Channel IDs to exclude
        live_sync_channels:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Live Sync Channels
          description: Channel IDs to enable real-time sync (bot joins these channels)
      type: object
      title: SlackChannelsConfigRequest
      description: Configure which channels to index.
    routes__v2__x__XInstallationRequest:
      properties:
        username:
          type: string
          title: Username
          description: X username to index (with or without @)
        bearer_token:
          type: string
          minLength: 10
          title: Bearer Token
          description: X API bearer token
        display_name:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          title: Display Name
          description: Optional custom display name for this source
        max_results:
          type: integer
          maximum: 10000
          minimum: 1
          title: Max Results
          description: Maximum number of recent posts to index
          default: 500
        include_replies:
          type: boolean
          title: Include Replies
          description: Whether replies should be indexed
          default: false
        include_retweets:
          type: boolean
          title: Include Retweets
          description: Whether reposts/retweets should be indexed
          default: false
      type: object
      required:
        - username
        - bearer_token
      title: XInstallationRequest
  securitySchemes: {}