openapi: 3.0.3
info:
  title: Nexus API
  description: |
    Nexus turns a set of sources into a queryable, self-improving knowledge base. A context is **sources + a manifest**: upload sources, **curate** them into a searchable index, then query it. The manifest, one validated JSON document, defines how the context indexes, retrieves and answers.

    Curate is explicit — nothing is queryable until you run it. `{slug}` accepts a context's slug or its UUID. Query with `POST /api/query`, one turn per call, and read the answer from `output[].content[].text`; multi-turn conversations are sessions. Tasks are project-owned at `/api/tasks`, not nested under contexts.
  contact:
    name: Pinecone Support
    url: https://support.pinecone.io
    email: support@pinecone.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 2026-07
servers:
- url: https://{host}/api
  description: Your Nexus deployment host
  variables:
    host:
      default: api.example.com
      description: Host of your Nexus deployment.
paths:
  /auth/login:
    post:
      tags:
      - Auth
      summary: Exchange a Pinecone API key for a session token
      description: Exchange a Pinecone API key for the session token every other endpoint expects. Send the token as a bearer credential.
      operationId: login
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
        required: true
      responses:
        '200':
          description: Session token + identity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Missing or invalid credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'Not permitted. Coded cases: `preview_not_enabled` (project not enabled for the Nexus preview), `workspace_host_required` (reached over the account host on a workspace-enabled cluster).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No workspace exists at this host (`workspace_not_found`), on a workspace-enabled cluster.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security: []
  /auth:
    get:
      tags:
      - Auth
      summary: Current identity (whoami)
      description: Who the current credential authenticates, and which project and workspace it is scoped to.
      operationId: get_identity
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: The caller's identity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityResponse'
        '401':
          description: Missing or invalid credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /project:
    get:
      tags:
      - Project
      summary: Get the active project
      description: The project the session is scoped to, plus whether this deployment requires a workspace host.
      operationId: get_project
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: The project, plus whether this deployment requires a workspace host
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectWithWorkspaces'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /connectors:
    get:
      tags:
      - Connectors
      summary: List the project's linked connectors
      description: The project's linked source providers. Filter by `kind` to those valid for a context kind.
      operationId: list_connectors
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      - in: query
        name: kind
        description: Filter to providers valid for this context kind.
        schema:
          description: How the context is built. `search` — built from source documents, and must be curated before it can be queried. `work` — built from traces of work done, queryable immediately, consolidated by `groom` rather than `curate`.
          default: search
          x-enum:
          - search
          - work
          type: string
        style: form
      responses:
        '200':
          description: Linked connectors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorList'
  /connectors/{id}:
    get:
      tags:
      - Connectors
      summary: Get a connector
      description: One linked connector, secrets stripped.
      operationId: get_connector
      parameters:
      - in: path
        name: id
        description: Connector id.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: The connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorView'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Connectors
      summary: Unlink a connector
      description: Unlink the connector from the project. Sources it already imported stay in place.
      operationId: delete_connector
      parameters:
      - in: path
        name: id
        description: Connector id.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedConnector'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /connectors/oauth/{provider}/start:
    get:
      tags:
      - Connectors
      summary: Start the OAuth link flow for a provider
      description: Returns an `authorize_url` for the user to open in a browser. The connector is persisted by the provider's OAuth redirect callback once the user approves access.
      operationId: start_connector_oauth
      parameters:
      - in: path
        name: provider
        description: Provider id (e.g. box)
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: return_to
        description: Console path to bounce back to after the callback
        schema:
          type: string
        style: form
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Authorization URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorOauthStart'
        '400':
          description: Unknown provider, or the provider is key-based
  /connectors/keys/{provider}:
    post:
      tags:
      - Connectors
      summary: Link a connector with an API key
      description: Link a key-based provider by supplying its API key directly, instead of running the OAuth flow.
      operationId: create_connector
      parameters:
      - in: path
        name: provider
        description: A key-based provider (e.g. parallel)
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectorRequest'
        required: true
      responses:
        '200':
          description: The linked connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorView'
        '400':
          description: Unknown provider, provider uses OAuth, or empty api_key
  /connectors/{id}/items:
    get:
      tags:
      - Connectors
      summary: Browse a connector's folders/files
      description: Browse the provider's folders and files to find the ids to import. Omit `folder` for the root.
      operationId: list_connector_items
      parameters:
      - in: path
        name: id
        description: Connector id.
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: folder
        description: Folder id to browse (root when absent)
        schema:
          type: string
        style: form
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: The folder browsed plus its children
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorItemList'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/connectors:
    get:
      tags:
      - Connectors
      summary: List a context's connectors (with per-context enabled flag)
      description: The project's connectors, each with whether this context may import from it.
      operationId: list_context_connectors
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Context connectors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextConnectorList'
        '404':
          description: Context not found
  /contexts/{slug}/connectors/{connector_id}:
    put:
      tags:
      - Connectors
      summary: Enable or disable a connector for a context
      description: Enable or disable one connector for this context.
      operationId: update_context_connector
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: connector_id
        description: Connector id.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContextConnectorRequest'
        required: true
      responses:
        '200':
          description: The updated context connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextConnectorView'
        '400':
          description: Provider does not support this context kind
        '404':
          description: Context or connector not found
  /contexts:
    get:
      tags:
      - Contexts
      summary: List contexts (newest first, with stats)
      description: Every context in the active project, newest first, each with its aggregate task counters.
      operationId: list_contexts
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Contexts visible to the caller in the active project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextList'
    post:
      tags:
      - Contexts
      summary: Create a context
      description: 'Created empty, and not queryable until you import sources and curate them — curate is explicit. Optionally seed a `manifest`. A `work` context is the exception: queryable from day zero, built from traces of work rather than documents.'
      operationId: create_context
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContextRequest'
        required: true
      responses:
        '200':
          description: The created context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Project not enabled for the Nexus preview (`preview_not_enabled`), or a per-plan context cap blocks creation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Slug already exists
  /contexts/{slug}:
    get:
      tags:
      - Contexts
      summary: Get a context
      description: One context and its derived lifecycle flags.
      operationId: get_context
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: The context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
      - Contexts
      summary: Update a context
      description: All fields optional; an absent one is left untouched. An empty string clears `description`/`guide`, and `{}` clears the manifest back to defaults.
      operationId: update_context
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContextRequest'
        required: true
      responses:
        '200':
          description: The updated context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Slug conflict
    delete:
      tags:
      - Contexts
      summary: Delete a context (and its Pinecone indexes)
      description: Delete the context, its sources, its curated knowledge, and its Pinecone indexes. Not reversible.
      operationId: delete_context
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Deleted (empty body)
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: Active tasks did not terminate in time
  /contexts/{slug}/manifest:
    get:
      tags:
      - Manifest
      summary: Get the context's manifest
      description: The context's pinned manifest document. A context that pins nothing returns `null` — the runtime fills defaults. Writes go through the `manifest` field on `PUT /contexts/{slug}`.
      operationId: get_context_manifest
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: The manifest document, or `null` when the context pins none
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NullableManifest'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/tasks/stats:
    get:
      tags:
      - Contexts
      summary: Per-context task statistics
      description: Aggregate counters over every task this context has run. The project-wide equivalent is `GET /stats`.
      operationId: get_context_task_stats
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Aggregate task counters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextStats'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/curate:
    get:
      tags:
      - Curation
      summary: Get the curation ledger
      description: 'What the last curate recorded: the per-source hash and timestamp map, artifact edges, corpus groups, the live version pin, delete tombstones, artifact-reclaim intents, and the pointer and glossary resume cursors. Chunk ids are tracked too but not served — an internal retrieval unit.'
      operationId: get_curation_ledger
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Curation state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurationState'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Curation
      summary: Build or rebuild the context's index from its sources
      description: 'Curate the staged sources under the active manifest. **Required before querying** — there is no auto-curate. Body is optional; `force: true` rebuilds fully, which is what a manifest edit needs. Search contexts only: a work context builds via `work`/`groom`.'
      operationId: curate_context
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CurateContextRequest'
      responses:
        '200':
          description: 'Curate enqueued (`state: importing`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowTriggerResponse'
        '400':
          description: Context is a work context
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Context has no sources, is optimizing, or hit the preview task cap
  /contexts/{slug}/curate/delete-sources:
    post:
      tags:
      - Curation
      summary: Drop named sources from the index + ledger
      description: Drop named sources from the index and the curation ledger without re-reading the rest of the corpus.
      operationId: delete_curated_sources
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteCuratedSourcesRequest'
        required: true
      responses:
        '200':
          description: Done (empty body)
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/optimize:
    post:
      tags:
      - Contexts
      summary: Trigger an on-demand self-tuning optimize
      description: Tunes the manifest from real query traffic, then chains a forced re-curate. Every field of the required body is optional, so `{}` is valid — and a no-op without `candidate_queries`. The context must be curated, and only one optimize runs at a time.
      operationId: optimize_context
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OptimizeContextRequest'
        required: true
      responses:
        '200':
          description: 'Optimize enqueued (`state: optimizing`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowTriggerResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Context is already optimizing or was never curated
  /contexts/{slug}/explore:
    post:
      tags:
      - Contexts
      summary: Run the Design-flow explore agent (propose a manifest)
      description: Inspects the uploaded source and proposes manifest-template matches in the task's `output` (see `ExploreOutput`). Persists nothing — review the proposal, then apply it with a manifest update and a forced curate. Body is optional.
      operationId: explore_context
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExploreContextRequest'
      responses:
        '200':
          description: 'Explore enqueued (`state: exploring`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowTriggerResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: An explore is already in progress
  /contexts/{slug}/profile:
    post:
      tags:
      - Contexts
      summary: Estimate the token + time cost of curating the in-progress manifest
      description: Estimates the token and time cost of curating the sources under the manifest in the request body, reported as the task's `output` (see `ProfileEstimateOutput`). Persists nothing. Body is optional.
      operationId: profile_context
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileContextRequest'
      responses:
        '200':
          description: 'Profile enqueued (`state: profiling`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowTriggerResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/import:
    post:
      tags:
      - Source Files
      summary: Import source documents from a project connector
      description: Pull source documents from a linked project connector (Box, ...) into the context. Supply either `folder` or `files`. Stages the source only — curate explicitly before querying.
      operationId: import_context_sources
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportContextSourcesRequest'
        required: true
      responses:
        '200':
          description: 'Import accepted (`state: importing`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowTriggerResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Context or connector not found
        '409':
          description: Context is optimizing, or an import is already in flight
  /contexts/{slug}/import/upload:
    post:
      tags:
      - Source Files
      summary: Upload a source file or archive
      description: One file per request, max 2 GiB; archives (`.zip`, `.tar`, `.tar.gz`, `.tgz`) are expanded by the import runtime. Stages the source without indexing it — curate explicitly before querying.
      operationId: upload_context_source
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: path
        description: Subdirectory under the source tree
        schema:
          default: uploads
          type: string
        style: form
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadContextSourceRequest'
        required: true
      responses:
        '200':
          description: 'Upload accepted; import enqueued (`state: importing`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowTriggerResponse'
        '400':
          description: Missing/unsafe file name, or archives disallowed in preview
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Context is optimizing, an import is in flight, or the preview file cap was hit (`preview_file_limit`)
        '413':
          description: File exceeds 2 GiB, or the preview byte cap was hit (`preview_byte_limit`)
  /contexts/{slug}/source/list:
    get:
      tags:
      - Source Files
      summary: List the source file tree (root)
      description: The root of the source tree — what has been staged but not necessarily curated.
      operationId: list_source_files
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: offset
        description: Where the page starts. Source and knowledge listings echo it rather than applying it, since they return the whole directory in one page.
        schema:
          type: integer
          format: int64
        style: form
      - in: query
        name: limit
        description: Maximum entries in the page. Source and knowledge listings echo it rather than applying it, since they return the whole directory in one page.
        schema:
          type: integer
          format: int64
        style: form
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Directory listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirListing'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/source/stats:
    get:
      tags:
      - Source Files
      summary: Source file/dir/size counts
      description: Aggregate counts. Where source limits apply, five more fields carry the caps and usage against them (`max_files_per_context`, `max_bytes_per_context`, `max_bytes_per_file`, `used_files`, `used_bytes`); they are absent otherwise.
      operationId: get_source_stats
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceStats'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/source/manifest:
    get:
      tags:
      - Source Files
      summary: Flat manifest of source files (path, size, last_modified)
      description: Flat source-object inventory. Excludes the `_inbox/` staging directory.
      operationId: get_source_manifest
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Source manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceFileManifest'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/source/list/{path}:
    get:
      tags:
      - Source Files
      summary: List the source file tree under a path
      description: One directory of the source tree.
      operationId: list_source_files_by_path
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: path
        description: Relative path within the tree. Matches greedily, so it may contain `/`.
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: offset
        description: Where the page starts. Source and knowledge listings echo it rather than applying it, since they return the whole directory in one page.
        schema:
          type: integer
          format: int64
        style: form
      - in: query
        name: limit
        description: Maximum entries in the page. Source and knowledge listings echo it rather than applying it, since they return the whole directory in one page.
        schema:
          type: integer
          format: int64
        style: form
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Directory listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirListing'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/source/read/{path}:
    get:
      tags:
      - Source Files
      summary: Read a source file (raw bytes)
      description: The raw bytes of one staged source file.
      operationId: read_source_file
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: path
        description: Relative path within the tree. Matches greedily, so it may contain `/`.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: File contents
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/FileBytes'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/source/delete/{path}:
    delete:
      tags:
      - Source Files
      summary: Delete a source file
      description: Remove one file from the source tree. Its index entries survive until the next curate.
      operationId: delete_source_file
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: path
        description: Relative path within the tree. Matches greedily, so it may contain `/`.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedSourceFile'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/knowledge/list:
    get:
      tags:
      - Knowledge
      summary: List curated knowledge (root)
      description: The root of the curated knowledge tree — chunks and artifacts the last curate wrote.
      operationId: list_knowledge
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: offset
        description: Where the page starts. Source and knowledge listings echo it rather than applying it, since they return the whole directory in one page.
        schema:
          type: integer
          format: int64
        style: form
      - in: query
        name: limit
        description: Maximum entries in the page. Source and knowledge listings echo it rather than applying it, since they return the whole directory in one page.
        schema:
          type: integer
          format: int64
        style: form
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Directory listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirListing'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/knowledge/stats:
    get:
      tags:
      - Knowledge
      summary: Knowledge file/dir/size counts
      description: File, directory, and byte counts over the curated knowledge tree.
      operationId: get_knowledge_stats
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStats'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/knowledge/list/{path}:
    get:
      tags:
      - Knowledge
      summary: List curated knowledge under a path
      description: One directory of the curated knowledge tree.
      operationId: list_knowledge_by_path
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: path
        description: Relative path within the tree. Matches greedily, so it may contain `/`.
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: offset
        description: Where the page starts. Source and knowledge listings echo it rather than applying it, since they return the whole directory in one page.
        schema:
          type: integer
          format: int64
        style: form
      - in: query
        name: limit
        description: Maximum entries in the page. Source and knowledge listings echo it rather than applying it, since they return the whole directory in one page.
        schema:
          type: integer
          format: int64
        style: form
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Directory listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirListing'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contexts/{slug}/knowledge/read/{path}:
    get:
      tags:
      - Knowledge
      summary: Read a curated knowledge file (raw bytes)
      description: The raw bytes of one curated knowledge file.
      operationId: read_knowledge_file
      parameters:
      - in: path
        name: slug
        description: Context slug or UUID.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: path
        description: Relative path within the tree. Matches greedily, so it may contain `/`.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: File contents
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/FileBytes'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /query:
    post:
      tags:
      - Query
      summary: Run one KnowQL query turn
      description: |
        Send `ask` and, on a new session, a `scope` of 1–10 contexts; continue an existing one with
        `session_id` or `previous_query_id`. Scoped search contexts must be curated, and a scope may
        not mix work and search contexts. Read the answer from `output[].content[].text`.

        `stream` and `background` are mutually exclusive. `background: true` returns `202` with an
        `in_progress` query to poll. `stream: true` emits an SSE stream whose `event:` names are the
        event `type` (see `QueryEvent`), closed by a final `query` frame carrying the whole turn:

        ```
        id: 1
        event: response.created
        data: {"type":"response.created","query_id":"qry_8b3d5f1a","session_id":"ses_4f9c1e2a"}

        id: 2
        event: response.output_text.delta
        data: {"type":"response.output_text.delta","query_id":"qry_8b3d5f1a","delta":"Revenue grew 12%..."}

        id: 3
        event: response.completed
        data: {"type":"response.completed","query_id":"qry_8b3d5f1a"}

        event: query
        data: {"id":"qry_8b3d5f1a","object":"query","status":"completed","output":[...]}
        ```
      operationId: query
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
        required: true
      responses:
        '200':
          description: The completed query turn (synchronous), or the SSE stream when `stream=true`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Query'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/QueryStream'
        '202':
          description: Accepted (background); poll GET /queries/{id}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Query'
        '400':
          description: Missing/invalid `ask`, mixed-kind scope, unavailable model, or stream+background together
        '404':
          description: Scoped context, session, or previous_query_id not found
        '409':
          description: A scoped context is not curated, a query is already in flight on the session, or a preview cap was hit
        '504':
          description: Turn timed out (15-minute cap, or a lower `timeout_seconds`)
  /queries/{id}:
    get:
      tags:
      - Query
      summary: Fetch one query (turn)
      description: One turn, including its steps, citations, and usage. This is what a background run is polled with.
      operationId: get_query
      parameters:
      - in: path
        name: id
        description: Query turn id.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: The query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Query'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /queries/{id}/cancel:
    post:
      tags:
      - Query
      summary: Cancel an in-progress query turn
      description: Idempotent — an already-terminal query is returned unchanged. On success the turn's `status` becomes `cancelled`.
      operationId: cancel_query
      parameters:
      - in: path
        name: id
        description: Query turn id.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: The (now cancelled) query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Query'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /queries/{id}/trace:
    get:
      tags:
      - Query
      summary: Fetch the recorded trace for a query turn
      description: The per-turn debug trace (steps, tool calls, strategy, cost, rollup). Trace persistence is unconditional — every turn lands a trace blob — so this is available once the turn is terminal.
      operationId: get_query_trace
      parameters:
      - in: path
        name: id
        description: Query turn id.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: The trace document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trace'
        '404':
          description: Query or trace not found
  /queries/{id}/events:
    get:
      tags:
      - Query
      summary: Stream a query turn's events (SSE)
      description: 'The turn''s events as they land — the same `type`-named events `POST /query` emits with `stream: true`, as a standalone resumable subscription. Reconnect with `Last-Event-ID` to replay from where the stream dropped.'
      operationId: stream_query_events
      parameters:
      - in: path
        name: id
        description: Query turn id.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: Last-Event-ID
        description: Resume from this event seq; delivery is inclusive of the given id (re-sending the last event is harmless — clients merge steps idempotently by step_id).
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: SSE event stream; each `event:` name is the event `type` and `data:` is its JSON payload.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/QueryStream'
        '404':
          description: Query not found
  /queries/{id}/feedback:
    post:
      tags:
      - Query
      summary: Record thumbs-up/down feedback on a query turn
      description: Record a thumbs-up or thumbs-down on a turn. The rating is returned on the turn thereafter.
      operationId: create_query_feedback
      parameters:
      - in: path
        name: id
        description: Query turn id.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQueryFeedbackRequest'
        required: true
      responses:
        '204':
          description: Recorded (empty body)
        '400':
          description: Invalid rating
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /models:
    get:
      tags:
      - Query
      summary: List the selectable query models
      description: 'What the `model` field on `POST /query` draws from: the default, every catalog entry, the tier → model-id map, per-phase defaults, and the curate-capable ids. Only entries with `available: true` are selectable; the rest are rejected with `400`.'
      operationId: list_models
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: The model catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelCatalog'
  /sessions:
    get:
      tags:
      - Query
      summary: List project-wide query sessions (newest first)
      description: Every conversation thread in the project, newest first.
      operationId: list_sessions
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      - in: query
        name: limit
        description: Maximum sessions to return.
        schema:
          default: 50
          type: integer
          minimum: 1
          maximum: 200
        style: form
      - in: query
        name: queries_active
        description: Also count the project's in-flight query turns, returned as `queries_active`.
        schema:
          default: false
          type: boolean
        style: form
      responses:
        '200':
          description: Sessions across the project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionList'
  /sessions/{id}:
    get:
      tags:
      - Query
      summary: Get a session with its queries (conversation order)
      description: One session with its turns in conversation order.
      operationId: get_session
      parameters:
      - in: path
        name: id
        description: Session id.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: The session fields plus a `queries` array of query turns
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionWithQueries'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Query
      summary: Delete a session and its queries
      description: Delete a session and every turn belonging to it.
      operationId: delete_session
      parameters:
      - in: path
        name: id
        description: Session id.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Whether a session was actually removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedSession'
  /stats:
    get:
      tags:
      - Project
      summary: Project-wide task stats
      description: Aggregate task counters across the whole project (all contexts), broken down by state and workflow. The per-context equivalent is `GET /contexts/{slug}/tasks/stats`.
      operationId: get_project_task_stats
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Aggregate task stats for the project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectTaskStats'
  /manifest/templates:
    get:
      tags:
      - Manifest
      summary: List the built-in manifest templates
      description: The templates a new context can be seeded from.
      operationId: list_manifest_templates
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Template catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManifestTemplateCatalog'
  /tasks:
    get:
      tags:
      - Tasks
      summary: List tasks (project-wide, paginated)
      description: Task records across the project, newest first. Filter by workflow, state, or context, and page with `limit` plus `page` or `offset`.
      operationId: list_tasks
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      - in: query
        name: workflow
        description: Return only tasks of this workflow.
        schema:
          description: The canonical workflow name.
          x-enum:
          - optimize
          - curate
          - search
          - search_cc
          - search_rag
          - work
          - explore
          - profile
          - import
          - pack
          - restore
          - groom
          type: string
        style: form
      - in: query
        name: state
        description: Return only tasks in this state.
        schema:
          description: Where the run has got to. `scheduled` waits for its due time; `starting` and `provisioning` are a container being claimed and built; `running` is the work happening; `stopping` is a termination in progress. `completed`, `cancelled` and `failed` are terminal.
          x-enum:
          - scheduled
          - starting
          - provisioning
          - running
          - stopping
          - completed
          - cancelled
          - failed
          type: string
        style: form
      - in: query
        name: context
        description: Context slug or UUID
        schema:
          type: string
        style: form
      - in: query
        name: q
        description: Free-text over id/created_by/input
        schema:
          type: string
        style: form
      - in: query
        name: limit
        description: Maximum tasks per page.
        schema:
          default: 30
          type: integer
          minimum: 1
          maximum: 1000
        style: form
      - in: query
        name: page
        description: 1-based page to return. Ignored when `offset` is given.
        schema:
          default: 1
          type: integer
        style: form
      - in: query
        name: offset
        description: Where the page starts. Takes precedence over `page`.
        schema:
          type: integer
        style: form
      responses:
        '200':
          description: Paginated tasks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskList'
  /tasks/{id}:
    get:
      tags:
      - Tasks
      summary: Get a task (with steps)
      description: Unlike the listing, this carries the task's `steps` — every one by default, or the newest N with `steps_limit`, where `steps_total` reports the true count.
      operationId: get_task
      parameters:
      - in: path
        name: id
        description: Task id.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      - in: query
        name: steps_limit
        description: Return only this many trailing steps. Absent returns them all.
        schema:
          type: integer
          minimum: 0
        style: form
      responses:
        '200':
          description: The task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Tasks
      summary: Cancel/terminate a task
      description: Body is optional. Max body 1 MiB.
      operationId: cancel_task
      parameters:
      - in: path
        name: id
        description: Task id.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelTaskRequest'
      responses:
        '200':
          description: Termination enqueued (empty body)
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: Task did not terminate in time
  /tasks/{id}/files/read/{path}:
    get:
      tags:
      - Task Files
      summary: Read a task file (raw bytes)
      description: Serves a task's files while it runs and after it finishes. This is how a finished pack's `<slug>.context.zip` is downloaded.
      operationId: read_task_file
      parameters:
      - in: path
        name: id
        description: Task id.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: path
        description: Relative path within the tree. Matches greedily, so it may contain `/`.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: File contents
          headers:
            x-nexus-file-size:
              description: Byte size, when known.
              style: simple
              schema:
                type: integer
                format: int64
            x-nexus-stale:
              description: Present when the bytes came from a stale archive copy.
              style: simple
              schema:
                x-enum:
                - 'true'
                type: string
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/FileBytes'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tasks/{id}/files/metadata/{path}:
    get:
      tags:
      - Task Files
      summary: Stat a task file
      description: Stat one file in the task container without reading its bytes.
      operationId: get_task_file_metadata
      parameters:
      - in: path
        name: id
        description: Task id.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: path
        description: Relative path within the tree. Matches greedily, so it may contain `/`.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: File metadata — the archived or the live shape, depending on task state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskFileMetadata'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tasks/{id}/files/list/{path}:
    get:
      tags:
      - Task Files
      summary: List a task's files under a path
      description: One directory inside the task's working directory.
      operationId: list_task_files_by_path
      parameters:
      - in: path
        name: id
        description: Task id.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: path
        description: Relative path within the tree. Matches greedily, so it may contain `/`.
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: offset
        description: Where the page starts. Source and knowledge listings echo it rather than applying it, since they return the whole directory in one page.
        schema:
          type: integer
          format: int64
        style: form
      - in: query
        name: limit
        description: Maximum entries in the page. Source and knowledge listings echo it rather than applying it, since they return the whole directory in one page.
        schema:
          type: integer
          format: int64
        style: form
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Directory listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskFileListing'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tasks/{id}/files/list:
    get:
      tags:
      - Task Files
      summary: List a task's working-directory files
      description: The root of the task's working directory.
      operationId: list_task_files
      parameters:
      - in: path
        name: id
        description: Task id.
        required: true
        schema:
          type: string
        style: simple
      - in: query
        name: offset
        description: Where the page starts. Source and knowledge listings echo it rather than applying it, since they return the whole directory in one page.
        schema:
          type: integer
          format: int64
        style: form
      - in: query
        name: limit
        description: Maximum entries in the page. Source and knowledge listings echo it rather than applying it, since they return the whole directory in one page.
        schema:
          type: integer
          format: int64
        style: form
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Directory listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskFileListing'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tasks/{id}/files/delete/{path}:
    delete:
      tags:
      - Task Files
      summary: Delete a task file
      description: Delete one file from a running task container.
      operationId: delete_task_file
      parameters:
      - in: path
        name: id
        description: Task id.
        required: true
        schema:
          type: string
        style: simple
      - in: path
        name: path
        description: Relative path within the tree. Matches greedily, so it may contain `/`.
        required: true
        schema:
          type: string
        style: simple
      - in: header
        name: X-Pinecone-Api-Version
        description: Date-based contract version, echoed back on the same header. Omit for the default (`2026-07`); send `unstable` for the in-development surface. An unrecognized value is rejected with `400 unsupported_api_version`.
        schema:
          default: 2026-07
          x-enum:
          - 2026-07
          - unstable
          type: string
        style: simple
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedTaskFile'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ArchivedFileListing:
      title: Archived
      description: Read after the task's files were archived.
      type: object
      properties:
        entries:
          description: The directory's immediate children.
          type: array
          items:
            description: One file or directory.
            type: object
            properties:
              name:
                description: Entry name, not a full path.
                type: string
              kind:
                description: Whether the entry is a file or a directory.
                x-enum:
                - dir
                - file
                type: string
              size:
                description: Byte size. 0 for a directory.
                type: integer
                format: int64
              mtime:
                description: RFC3339 last-modified, or empty when the store reports none.
                type: string
            required:
            - name
            - kind
            - size
            - mtime
        total:
          description: Entries in the directory.
          type: integer
          format: int64
        offset:
          description: Where this page starts.
          type: integer
          format: int64
        limit:
          description: Maximum entries in this page.
          type: integer
          format: int64
        next_offset:
          nullable: true
          description: Null on the last page.
          type: integer
          format: int64
      required:
      - entries
      - total
      - offset
      - limit
      - next_offset
    ArtifactReclaim:
      description: An intent to swap one artifact for its replacement, recorded so the old one is dropped only once the new one is live.
      type: object
      properties:
        removed_id:
          description: The artifact being superseded.
          type: string
        added_id:
          description: The artifact replacing it.
          type: string
        version:
          description: Index version the swap belongs to.
          type: integer
          format: int64
      required:
      - removed_id
      - added_id
      - version
    ArtifactType:
      description: One kind of artifact to extract. `name` is required of a written manifest; a read echoes a stored document that lacks one rather than failing.
      type: object
      properties:
        name:
          description: What the type is called. Edge endpoints reference it, and a sqlite type's table is named after it.
          type: string
          maxLength: 64
        kind:
          description: What the artifact represents, which selects the extraction prompt. `glossary` is the exception — it reads the headings named in `sections` deterministically, with no LLM call.
          default: topic
          x-enum:
          - summary
          - topic
          - entity
          - event
          - doc
          - page
          - glossary
          type: string
        scope:
          description: How widely the extraction reaches. `document` extracts one artifact per source; `corpus` reduces mentions from across every source into one artifact per subject.
          default: corpus
          x-enum:
          - document
          - corpus
          type: string
        icon:
          description: Symbol to display beside artifacts of this kind.
          type: string
          maxLength: 64
        description:
          description: What this type should capture. Goes into the extraction prompt, so it steers the result.
          type: string
          maxLength: 512
        coverage:
          description: Topics the extraction is told to address wherever the source speaks to them.
          type: array
          items:
            description: One topic the extraction should address.
            type: string
            maxLength: 128
          maxItems: 32
        sections:
          description: Exact section headings a `glossary`-kind type reads verbatim. Ignored by every other kind.
          type: array
          items:
            description: One exact section heading to read.
            type: string
            maxLength: 128
          maxItems: 64
        min_doc_count:
          description: Overrides the manifest-level `min_doc_count` for this type.
          default: 1
          type: integer
          minimum: 1
          maximum: 64
        format:
          description: Where the artifacts of this type are written — `markdown` a prose file each, `sqlite` rows in the context's structured database.
          default: markdown
          x-enum:
          - markdown
          - sqlite
          type: string
        columns:
          description: Table schema for a `sqlite`-format type. Ignored for `markdown`. Two names that normalize to the same column collide, and the first declaration wins.
          type: array
          items:
            description: One column of the type's table.
            type: object
            properties:
              name:
                description: Column name.
                type: string
                maxLength: 64
              type:
                description: SQLite column affinity.
                default: TEXT
                x-enum:
                - TEXT
                - INTEGER
                - REAL
                - NUMERIC
                type: string
              description:
                description: What the column holds. Steers the extraction that fills it.
                type: string
                maxLength: 256
            required:
            - name
          maxItems: 64
        natural_key:
          description: Columns that identify a row uniquely, so re-curating a source upserts its rows rather than duplicating them. `sqlite`-format types only.
          type: array
          items:
            description: One column of the upsert key.
            type: string
            maxLength: 64
          maxItems: 16
      required:
      - name
    ArtifactsConfig:
      description: 'The artifact leg: knowledge an LLM distills out of the sources, as prose files or database rows. Off by default.'
      type: object
      properties:
        enabled:
          description: Whether curate extracts artifacts at all.
          default: false
          type: boolean
        artifact_model:
          description: Model tier that does the extraction. `standard` reads more carefully at a higher token cost.
          default: lite
          x-enum:
          - standard
          - lite
          type: string
        artifact_types:
          description: What kinds of artifact to extract. Nothing is extracted until at least one is declared.
          type: array
          items:
            $ref: '#/components/schemas/ArtifactType'
          maxItems: 32
        edge_types:
          description: Typed, directed relationships between artifact types, which turn the artifacts into a graph the agent can traverse.
          type: array
          items:
            $ref: '#/components/schemas/EdgeType'
          maxItems: 32
        min_doc_count:
          description: How many source documents must mention a corpus-scoped subject before it earns an artifact. Raise it to suppress one-off mentions. An artifact type may override it.
          default: 1
          type: integer
          minimum: 1
          maximum: 64
        max_tokens:
          description: Output cap for one extracted artifact, in tokens.
          default: 1500
          type: integer
          minimum: 128
          maximum: 8192
        max_doc_chars:
          description: Input cap for one extraction call, in characters. With windowing off this also caps how much of a source is read at all; everything beyond it is dropped.
          default: 60000
          type: integer
          minimum: 1000
          maximum: 2000000
        extraction_window_chars:
          description: Window size for walking a long source across several extraction calls, so its back half is covered rather than dropped. `0` opts out and reads only the head, up to `max_doc_chars`.
          default: 0
          type: integer
          minimum: 0
          maximum: 1000000
        mention_max_chars:
          description: Cap on one recorded mention — what a single document says about the subject — in characters.
          default: 400
          type: integer
          minimum: 100
          maximum: 4000
        max_mentions_per_artifact:
          description: How many mentions are fed into the pass that reduces them into one corpus-wide artifact.
          default: 40
          type: integer
          minimum: 1
          maximum: 500
        mention_context_chars:
          description: Cap on those mentions once concatenated, in characters. Applied after `max_mentions_per_artifact`.
          default: 8000
          type: integer
          minimum: 1000
          maximum: 100000
        max_artifacts_per_type:
          description: How many artifacts one type may produce. Omit for no cap.
          default: 10000
          type: integer
          minimum: 1
          maximum: 10000
    CancelTaskRequest:
      description: Optional detail about the termination. A request with no body still terminates the task.
      type: object
      properties:
        reason:
          description: Why the task is being terminated, recorded on the row.
          type: string
        target:
          description: Which part of the task to terminate. Defaults to the whole task.
          type: string
        pinecone_api_key:
          description: Task-token override; normally not needed.
          type: string
        user_token:
          description: Caller-token override; normally not needed.
          type: string
    CandidateQuery:
      description: A query the optimize run tunes toward.
      type: object
      properties:
        ask:
          description: The question to tune retrieval against.
          type: string
        answer:
          description: Used as eval ground truth
          type: string
        fallback_to_chunks:
          description: Whether answering this query had to drill from artifacts down to chunks.
          type: boolean
        latency_ms:
          description: Latency the query showed in real traffic, as a tuning baseline.
          type: number
          format: double
    ChatUsage:
      description: What a run billed on the chat seam, in tokens. Reported by the inference client, which carries the cache-token fields. Used by optimize and explore.
      type: object
      properties:
        prompt_tokens:
          description: Input tokens billed across every model.
          type: integer
          format: int64
        completion_tokens:
          description: Output tokens billed across every model.
          type: integer
          format: int64
        total_tokens:
          description: Input plus output tokens across every model.
          type: integer
          format: int64
        by_model:
          description: Keyed by the model the proxy actually dispatched to, so tier fallbacks are visible.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ModelUsage'
        cache_read_tokens:
          description: Input served without re-billing.
          type: integer
          format: int64
        cache_write_tokens:
          description: Prompt tokens written into cache.
          type: integer
          format: int64
      required:
      - prompt_tokens
      - completion_tokens
      - total_tokens
      - by_model
      - cache_read_tokens
      - cache_write_tokens
    ChunkingConfig:
      description: How a source is cut into chunks.
      type: object
      properties:
        strategy:
          description: Which structure the splitter cuts on — markdown headings, fixed-size windows, HTML elements, CSV rows, or code syntax. Pick the one that matches the corpus.
          default: markdown_heading
          x-enum:
          - markdown_heading
          - sliding_window
          - html
          - csv
          - code
          type: string
        target_size:
          description: Chunk size the splitter aims for, in tokens. Smaller chunks retrieve more precisely; larger ones carry more surrounding context.
          default: 512
          type: integer
          minimum: 64
          maximum: 4096
        overlap:
          description: Tokens each chunk repeats from its predecessor, so a passage split across a boundary is still retrievable whole.
          default: 64
          type: integer
          minimum: 0
          maximum: 1024
        respect_sections:
          description: Never cut across a section boundary, even when that leaves a chunk short of `target_size`.
          default: true
          type: boolean
    ChunksConfig:
      description: The chunk leg — sources split into passages, embedded for semantic search and optionally indexed for keyword search.
      type: object
      properties:
        enabled:
          description: Whether curate builds the chunk leg at all.
          default: true
          type: boolean
        embedding_model:
          description: Model that embeds the chunks.
          default: multilingual-e5-large
          type: string
          maxLength: 128
        chunking:
          $ref: '#/components/schemas/ChunkingConfig'
        keyword:
          description: The lexical index built alongside the vectors, for exact-term matching.
          type: object
          properties:
            enabled:
              description: Whether the lexical index is built.
              default: true
              type: boolean
    Citation:
      description: 'What a turn''s answer was grounded in. Every field is optional: a search turn cites a corpus file (`source` and its pointers), a work turn the earlier turn a fact came from (`source_path`, `query_id`, `steps`, `artifact_name`).'
      type: object
      properties:
        source:
          description: Path of the cited corpus file, relative to the source-tree root.
          type: string
        section_paths:
          description: Heading paths within the source, when known. One inner array per cited section, outermost heading first.
          type: array
          items:
            description: One heading path, outermost heading first.
            type: array
            items:
              description: One heading in the path.
              type: string
        pages:
          description: 1-based page numbers, for sources that paginate.
          type: array
          items:
            description: A 1-based page number.
            type: integer
            format: int64
        score:
          description: Retrieval score — how well this source answered the ask. Comparable only within one turn.
          type: number
          format: double
        grounding:
          description: The quoted span the answer rests on.
          type: string
        kind:
          description: Which index the citation came out of, e.g. `chunk` or `artifact`.
          type: string
        source_path:
          description: Work contexts — path of the artifact the fact was consolidated into.
          type: string
        query_id:
          description: Work contexts — the earlier turn the fact was learned from.
          type: string
        steps:
          description: Work contexts — step ids within that earlier turn.
          type: array
          items:
            description: A step id within the cited turn.
            type: string
        artifact_name:
          description: Work contexts — name of the cited artifact.
          type: string
        sources:
          description: The documents a cited artifact was derived from.
          type: array
          items:
            description: One document the artifact was derived from.
            type: string
    ConnectorItem:
      description: One file or folder in the provider's tree, as offered for import.
      type: object
      properties:
        id:
          description: Provider-side id. Pass it as `folder` or in `files` to import.
          type: string
        name:
          description: Display name at the provider.
          type: string
        type:
          description: Whether the item is a file or a folder.
          x-enum:
          - file
          - folder
          type: string
        size:
          description: Files only, when the provider reports it
          type: integer
          format: int64
      required:
      - id
      - name
      - type
    ConnectorItemList:
      description: The folder that was browsed plus its children.
      type: object
      properties:
        folder:
          description: The folder id that was browsed
          type: string
        items:
          description: The folder's files and subfolders.
          type: array
          items:
            $ref: '#/components/schemas/ConnectorItem'
      required:
      - folder
      - items
    ConnectorList:
      description: The linked connectors.
      type: array
      items:
        $ref: '#/components/schemas/ConnectorView'
    ConnectorOauthStart:
      description: Where to send the user to approve access.
      type: object
      properties:
        authorize_url:
          description: The provider's consent page. Open it in a browser.
          type: string
      required:
      - authorize_url
    ConnectorView:
      description: A linked project connector, secrets stripped. There is no `config` field — the domain model carries a provider-specific blob, but no provider populates one today.
      type: object
      properties:
        id:
          description: Connector id, used to import from it.
          type: string
        provider:
          description: Which external system this links to, e.g. `box`.
          type: string
        account_label:
          nullable: true
          description: Display label distinguishing two links to the same provider. Null when none was given.
          type: string
        created_at:
          description: When the connector was linked.
          type: string
          format: date-time
        updated_at:
          description: When the connector last changed.
          type: string
          format: date-time
      required:
      - id
      - provider
      - created_at
      - updated_at
    ContextConnectorList:
      description: The connectors, each with its per-context enabled flag.
      type: array
      items:
        $ref: '#/components/schemas/ContextConnectorView'
    ContextConnectorView:
      description: A project connector as one context sees it, carrying that context's enabled flag.
      allOf:
      - $ref: '#/components/schemas/ConnectorView'
      - description: A project connector with its per-context enabled flag. Flat, not nested — the flag sits alongside the connector's own fields.
        type: object
        properties:
          enabled:
            description: Whether this context may import from the connector.
            type: boolean
        required:
        - enabled
    ContextKind:
      description: How the context is built. `search` — built from source documents, and must be curated before it can be queried. `work` — built from traces of work done, queryable immediately, consolidated by `groom` rather than `curate`.
      default: search
      x-enum:
      - search
      - work
      type: string
    ContextList:
      description: The contexts, newest first.
      type: array
      items:
        $ref: '#/components/schemas/ContextResponse'
    ContextResponse:
      description: What context endpoints return — the stored context plus the lifecycle flags derived from its in-flight tasks.
      type: object
      properties:
        id:
          description: Stable UUID. Accepted anywhere `{slug}` is.
          type: string
        slug:
          description: URL-safe name, unique within the project. Mutable via `PUT`.
          type: string
        name:
          description: Human-readable display name.
          type: string
        kind:
          $ref: '#/components/schemas/ContextKind'
        workspace:
          description: Owning workspace. Absent off a workspace-enabled cluster.
          type: string
        created_by:
          description: Principal that created the context.
          type: string
        description:
          nullable: true
          description: Free-text summary of what the context holds.
          type: string
        guide:
          description: High-level standing instructions the query runtime reads on every turn.
          type: string
        manifest:
          description: Pinned manifest document. Absent when the context runs on validator defaults.
          allOf:
          - $ref: '#/components/schemas/Manifest'
        semantic_index:
          nullable: true
          description: Host of the index backing this context's vector retrieval. Null until a curate resolves one.
          type: string
        keyword_index:
          nullable: true
          description: Host of the index backing keyword retrieval. The same host as `semantic_index` today — the two names are separate seams over one index.
          type: string
        is_optimizing:
          description: An optimize task is in flight.
          type: boolean
        optimize_task_id:
          nullable: true
          description: The optimize task — the running one, or the last to finish.
          type: string
        optimize_score:
          nullable: true
          description: Eval pass rate the last optimize's best iteration scored.
          type: number
          format: double
        optimize_iterations:
          nullable: true
          description: How many candidate manifests the last run tried.
          type: integer
        last_optimized_at:
          nullable: true
          description: When an optimize last persisted a tuned manifest.
          type: string
          format: date-time
        last_curated_at:
          nullable: true
          description: When a curate last flipped a new index version live.
          type: string
          format: date-time
        has_sources:
          description: The source tree holds at least one file. False blocks curate.
          type: boolean
        last_source_import_at:
          nullable: true
          description: When sources were last staged by an upload or import.
          type: string
          format: date-time
        is_curating:
          description: A curate task is in flight.
          type: boolean
        curate_task_id:
          nullable: true
          description: The curate task — the running one, or the last to finish.
          type: string
        is_importing:
          description: An import task is in flight.
          type: boolean
        import_task_id:
          nullable: true
          description: The import task — the running one, or the last to finish.
          type: string
        is_exploring:
          description: An explore task is in flight.
          type: boolean
        explore_task_id:
          nullable: true
          description: The explore task — the running one, or the last to finish.
          type: string
        is_restoring:
          description: A restore task is in flight.
          type: boolean
        restore_task_id:
          nullable: true
          description: The restore task — the running one, or the last to finish.
          type: string
        manifest_suggestion:
          $ref: '#/components/schemas/ManifestSuggestion'
        sample_queries:
          description: Example questions the curated corpus can answer, written by the last curate.
          type: array
          items:
            description: One example question.
            type: string
        is_grooming:
          description: A groom task is in flight. Work contexts only.
          type: boolean
        groom_task_id:
          description: The groom task — the running one, or the last to finish.
          type: string
        groom_artifact_count:
          description: Artifacts the last groom left in the work context.
          type: integer
          format: int64
        last_groomed_at:
          description: When a groom last consolidated the work context.
          type: string
          format: date-time
        created_at:
          description: When the context was created.
          type: string
          format: date-time
        updated_at:
          description: When the context last changed.
          type: string
          format: date-time
        stats:
          description: Aggregate task counters. Populated only on the list endpoint.
          allOf:
          - $ref: '#/components/schemas/ContextStats'
      required:
      - id
      - slug
      - name
      - kind
      - created_by
      - description
      - is_optimizing
      - has_sources
      - is_curating
      - is_importing
      - is_exploring
      - is_restoring
      - is_grooming
      - created_at
      - updated_at
    ContextStats:
      description: Aggregate counters over every task this context has ever run.
      type: object
      properties:
        tasks_total:
          description: Tasks this context has ever run.
          type: integer
          format: int64
        tasks_active:
          description: Tasks in a non-terminal state.
          type: integer
          format: int64
        tasks_completed:
          description: Tasks that finished successfully.
          type: integer
          format: int64
        tasks_failed:
          description: Tasks that ended in failure.
          type: integer
          format: int64
        tasks_cancelled:
          description: Runs stopped before they finished.
          type: integer
          format: int64
        tokens_total:
          description: Prompt plus completion tokens across every task.
          type: integer
          format: int64
        runtime_seconds:
          description: Summed container runtime across every task.
          type: integer
          format: int64
      required:
      - tasks_total
      - tasks_active
      - tasks_completed
      - tasks_failed
      - tasks_cancelled
      - tokens_total
      - runtime_seconds
    CorpusGroup:
      description: A set of sources the corpus pass treats as one subject, so their mentions reduce into a single artifact.
      type: object
      properties:
        group_key:
          description: Stable identifier the reduce pass groups on.
          type: string
        member_sources:
          description: Source paths in the group.
          type: array
          items:
            description: One source path in the group.
            type: string
        canonical_name:
          description: The name the group's artifact is written under.
          type: string
        membership_hash:
          description: Hash of the membership. A change here means the group must be re-reduced.
          type: string
        added_version:
          description: Index version the group was added in.
          type: integer
          format: int64
      required:
      - group_key
      - member_sources
      - canonical_name
      - membership_hash
      - added_version
    CreateConnectorRequest:
      description: The provider credential to store.
      type: object
      properties:
        api_key:
          description: The provider's API key. Stored encrypted and never returned.
          type: string
        account_label:
          description: Optional display label
          type: string
      required:
      - api_key
    CreateContextRequest:
      description: What a new context is created with. Only `slug` and `name` are required.
      type: object
      properties:
        slug:
          description: 3–64 chars, lowercase alnum + hyphens, starts with a letter
          type: string
        name:
          description: 1–128 chars
          type: string
        description:
          description: Free-text summary of what the context will hold.
          type: string
        guide:
          description: High-level standing instructions for the query runtime.
          type: string
        manifest:
          description: Seed manifest (validated against the manifest schema)
          allOf:
          - $ref: '#/components/schemas/Manifest'
        kind:
          $ref: '#/components/schemas/ContextKind'
        pinecone_api_key:
          description: Pinecone API key used to provision the context's managed index. Omit it under BYOC, where the deployment holds its own credential.
          type: string
      required:
      - slug
      - name
    CreateQueryFeedbackRequest:
      description: The rating to record.
      type: object
      properties:
        rating:
          description: Thumbs up or down.
          x-enum:
          - up
          - down
          type: string
        comment:
          description: Optional, trimmed
          type: string
          maxLength: 2000
      required:
      - rating
    CurateContextRequest:
      description: Optional overrides for the run. `{}` is a valid incremental curate.
      type: object
      properties:
        force:
          description: Full rebuild rather than incremental
          default: false
          type: boolean
        batch_size:
          description: How many sources curate reads per pass.
          type: integer
        scope:
          description: Curate scope recorded on the task input
          type: string
        trigger:
          description: Provenance label recorded on the task input
          type: string
        model:
          description: Model-id override for the curate runtime
          type: string
        pinecone_api_key:
          description: Task-token override; normally not needed
          type: string
    CurateInput:
      title: Curate
      description: What a curate run was started with.
      type: object
      properties:
        trigger:
          description: What started the run, e.g. `manual`, `reconcile`, `restore`, or `resume`.
          type: string
        force:
          description: Full rebuild rather than incremental.
          type: boolean
        scope:
          description: What the run covered, e.g. `full`, `reconcile`, or `restore`.
          type: string
        batch_size:
          description: Sources processed per batch.
          type: integer
        models:
          description: Model-id overrides for the curate runtime.
          type: array
          items:
            description: A catalog model id or tier name.
            type: string
        legs:
          description: Set to `["chunks"]` to gate the run to the chunk + keyword indices, skipping artifact extraction.
          type: array
          items:
            description: A leg name, e.g. `chunks`.
            type: string
        artifacts_reset:
          description: Drop the existing artifacts and re-extract from scratch.
          type: boolean
        skip_corpus_aggregation:
          description: Skip the corpus-wide artifact pass, leaving only per-document extraction.
          type: boolean
        claimed_version:
          description: What a drained predecessor had already reserved.
          type: integer
          format: int64
      required:
      - trigger
      - force
      - scope
    CurateManifest:
      description: What curate builds out of the sources — the chunk leg, the artifact leg, or both.
      type: object
      properties:
        chunks:
          $ref: '#/components/schemas/ChunksConfig'
        artifacts:
          $ref: '#/components/schemas/ArtifactsConfig'
    CurateManifestTuneOutput:
      title: Curate manifest_tune
      description: The post-optimize artifacts re-eval. Targets optimize trial namespaces, so `flipped` is always false and `mode` is always `manifest_tune`.
      type: object
      properties:
        status:
          description: How the run ended.
          type: string
        flipped:
          description: Always false — the run targets optimize trial namespaces, not the live index.
          x-enum:
          - false
          type: boolean
        versioned:
          description: Whether the run wrote version stamps.
          type: boolean
        mode:
          description: Always `manifest_tune`.
          x-enum:
          - manifest_tune
          type: string
        usage:
          $ref: '#/components/schemas/CurateUsage'
        delta:
          description: What the re-eval changed.
          type: object
          properties:
            artifacts_reevaluated:
              description: Artifacts re-extracted under the tuned manifest. Replaces the source counts a normal run reports.
              type: integer
              format: int64
            failed:
              description: Sources that could not be re-evaluated.
              type: integer
              format: int64
            failed_sources:
              description: Paths of the failed sources, capped in length.
              type: array
              items:
                description: A source path that failed.
                type: string
            failed_sources_truncated:
              description: Whether failed_sources was capped and the full list spilled to a file.
              type: boolean
            failed_sources_file:
              description: Where the full failed-sources list was written when truncated.
              type: string
            corpus_artifacts:
              description: Artifacts written by the corpus-wide reduce pass.
              type: integer
              format: int64
            corpus_edges:
              description: Edges written by that pass.
              type: integer
              format: int64
            chunks_created:
              description: Chunks written for the first time.
              type: integer
              format: int64
            chunks_updated:
              description: Chunks rewritten from changed sources.
              type: integer
              format: int64
            artifacts_created:
              description: Per-document artifacts written for the first time.
              type: integer
              format: int64
            artifacts_updated:
              description: Per-document artifacts rewritten from changed sources.
              type: integer
              format: int64
            chunks_screened:
              description: Chunks rejected by the quality screen.
              type: integer
              format: int64
            artifacts_screened:
              description: Per-document artifacts rejected by the quality screen.
              type: integer
              format: int64
            images_skipped_no_vision:
              description: Images left unread because the configured model cannot see.
              type: integer
              format: int64
            sources_skipped_unreadable:
              description: Sources no leg could read, skipped rather than failed.
              type: integer
              format: int64
            artifacts_errored:
              description: Extraction calls that failed outright.
              type: integer
              format: int64
            sources_content_truncated:
              description: Sources whose text was cut at the input cap.
              type: integer
              format: int64
          required:
          - artifacts_reevaluated
          - failed
          - failed_sources
          - failed_sources_truncated
          - failed_sources_file
          - corpus_artifacts
          - corpus_edges
          - chunks_created
          - chunks_updated
          - artifacts_created
          - artifacts_updated
          - chunks_screened
          - artifacts_screened
          - images_skipped_no_vision
          - sources_skipped_unreadable
          - artifacts_errored
          - sources_content_truncated
      required:
      - status
      - flipped
      - versioned
      - mode
      - usage
      - delta
    CurateNoopOutput:
      title: Curate no-op
      description: Nothing changed since the last run; `delta` is the literal string `empty` rather than a count block, which is what makes this a shape of its own.
      type: object
      properties:
        status:
          description: How the run ended.
          type: string
        flipped:
          description: Whether a new index version was made live.
          type: boolean
        versioned:
          description: Whether the run wrote version stamps.
          type: boolean
        mode:
          description: Set to `incremental` when the context has a manifest, `full` otherwise.
          type: string
        scope:
          description: What the run would have covered.
          type: string
        delta:
          description: Always the literal string `empty`.
          x-enum:
          - empty
          type: string
      required:
      - status
      - flipped
      - versioned
      - mode
      - scope
      - delta
    CurateRunOutput:
      title: Curate run
      description: What a curate run built. The index it wrote goes live only when `flipped` is true.
      type: object
      properties:
        status:
          description: How the run ended.
          type: string
        flipped:
          description: Whether the new index version was made live. False means queries still read the previous one.
          type: boolean
        versioned:
          description: Whether the run wrote version stamps.
          type: boolean
        mode:
          description: Set to `incremental` when the context has a manifest, `full` otherwise.
          type: string
        scope:
          description: What the run covered, e.g. `full` or `reconcile`.
          type: string
        images_skipped_no_vision:
          description: Images left unread because the configured model cannot see.
          type: integer
          format: int64
        sources_skipped_unreadable:
          description: Sources no leg could read, skipped rather than failed.
          type: integer
          format: int64
        usage:
          $ref: '#/components/schemas/CurateUsage'
        sample_queries:
          description: Example questions the corpus can answer
          type: array
          items:
            description: One example question.
            type: string
        delta:
          description: What the run changed, counted per leg.
          type: object
          properties:
            new:
              description: Sources not seen by a previous curate.
              type: integer
              format: int64
            changed:
              description: Sources whose content hash moved.
              type: integer
              format: int64
            deleted:
              description: Sources dropped from the index.
              type: integer
              format: int64
            processed:
              description: Sources the run actually read.
              type: integer
              format: int64
            failed:
              description: Sources that could not be curated.
              type: integer
              format: int64
            failed_sources:
              description: Paths of the failed sources, capped in length.
              type: array
              items:
                description: A source path that failed.
                type: string
            failed_sources_truncated:
              description: Whether failed_sources was capped and the full list spilled to a file
              type: boolean
            failed_sources_file:
              description: Where the full failed-sources list was written when truncated
              type: string
            corpus_artifacts:
              description: Artifacts written by the corpus-wide reduce pass.
              type: integer
              format: int64
            corpus_edges:
              description: Edges written by that pass.
              type: integer
              format: int64
            corpus_artifacts_screened:
              description: Corpus artifacts rejected by the quality screen.
              type: integer
              format: int64
            screened:
              description: Sum of the per-leg and corpus screen counts
              type: integer
              format: int64
            chunks_created:
              description: Chunks written for the first time.
              type: integer
              format: int64
            chunks_updated:
              description: Chunks rewritten from changed sources.
              type: integer
              format: int64
            artifacts_created:
              description: Per-document artifacts written for the first time.
              type: integer
              format: int64
            artifacts_updated:
              description: Per-document artifacts rewritten from changed sources.
              type: integer
              format: int64
            chunks_screened:
              description: Chunks rejected by the quality screen.
              type: integer
              format: int64
            artifacts_screened:
              description: Per-document artifacts rejected by the quality screen.
              type: integer
              format: int64
            images_skipped_no_vision:
              description: Images left unread because the configured model cannot see.
              type: integer
              format: int64
            sources_skipped_unreadable:
              description: Sources no leg could read, skipped rather than failed.
              type: integer
              format: int64
            artifacts_errored:
              description: Extraction calls that failed outright.
              type: integer
              format: int64
            sources_content_truncated:
              description: Sources whose text was cut at the input cap, so their tail went unread.
              type: integer
              format: int64
          required:
          - new
          - changed
          - deleted
          - processed
          - failed
          - failed_sources
          - failed_sources_truncated
          - failed_sources_file
          - corpus_artifacts
          - corpus_edges
          - corpus_artifacts_screened
          - screened
          - chunks_created
          - chunks_updated
          - artifacts_created
          - artifacts_updated
          - chunks_screened
          - artifacts_screened
          - images_skipped_no_vision
          - sources_skipped_unreadable
          - artifacts_errored
          - sources_content_truncated
      required:
      - status
      - flipped
      - versioned
      - mode
      - scope
      - images_skipped_no_vision
      - sources_skipped_unreadable
      - usage
      - sample_queries
      - delta
    CurateUsage:
      description: 'Curate''s token rollup: the chat-seam totals plus the embed/rerank seam (`embed_by_model`). It does not carry the cache-token fields.'
      type: object
      properties:
        prompt_tokens:
          description: Input tokens billed on the chat seam.
          type: integer
          format: int64
        completion_tokens:
          description: Output tokens billed on the chat seam.
          type: integer
          format: int64
        total_tokens:
          description: Input plus output tokens on the chat seam.
          type: integer
          format: int64
        by_model:
          description: Chat-seam counts keyed by the model the proxy actually dispatched to.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ModelUsage'
        embed_by_model:
          description: Embed and rerank counts keyed by model. These bill separately from the chat totals above and are not included in them.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SeamUsage'
      required:
      - prompt_tokens
      - completion_tokens
      - total_tokens
      - by_model
      - embed_by_model
    CurationState:
      description: What the last curate recorded, and what the next one resumes from.
      type: object
      properties:
        manifest:
          description: Per-source curate ledger, keyed by source path.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SourceManifestEntry'
        edges:
          description: Artifact ids each source contributed an edge to, keyed by source path.
          type: object
          additionalProperties:
            description: Artifact ids this source contributed an edge to.
            type: array
            items:
              description: One artifact id.
              type: string
        corpus_groups:
          description: The source groupings the corpus pass reduced over.
          type: array
          items:
            $ref: '#/components/schemas/CorpusGroup'
        live_version:
          description: The index version queries read.
          type: integer
          format: int64
        versions_stamped:
          description: Whether every index entry carries a version stamp, which is what lets a curate flip versions atomically.
          type: boolean
        source_removed:
          description: Delete tombstones awaiting the next curate, keyed by source path.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SourceRemoved'
        redispatch_count:
          description: How many times a curate on this context was killed and redispatched. The checkpointed run resumes rather than restarting.
          type: integer
        artifact_reclaim:
          description: Artifact swaps awaiting the next curate.
          type: array
          items:
            $ref: '#/components/schemas/ArtifactReclaim'
        source_pointers:
          description: The resume cursor a redispatched curate writes, keyed by source path. `{}` for a context whose curates all ran to completion.
          type: object
          additionalProperties:
            description: Mentions recorded for this source.
            type: array
            items:
              $ref: '#/components/schemas/PointerEntry'
        source_glossary:
          description: The glossary resume cursor, keyed by source path. `{}` for a context whose curates all ran to completion.
          type: object
          additionalProperties:
            description: Terms read verbatim out of the named file.
            type: array
            items:
              $ref: '#/components/schemas/GlossaryEntry'
      required:
      - manifest
      - edges
      - corpus_groups
      - live_version
      - versions_stamped
      - source_removed
      - redispatch_count
      - artifact_reclaim
      - source_pointers
      - source_glossary
    DeleteCuratedSourcesRequest:
      description: Which sources to drop.
      type: object
      properties:
        sources:
          description: Source paths to remove from the index and the ledger.
          type: array
          items:
            description: A source path.
            type: string
      required:
      - sources
    DeletedConnector:
      description: Confirmation naming the connector that was unlinked.
      type: object
      properties:
        deleted:
          description: The deleted connector id
          type: string
      required:
      - deleted
    DeletedSession:
      description: Whether a session was actually removed.
      type: object
      properties:
        deleted:
          description: False when no session existed under that id.
          type: boolean
      required:
      - deleted
    DeletedSourceFile:
      description: Confirmation naming the file that was removed.
      type: object
      properties:
        deleted:
          description: Whether the file was removed.
          type: boolean
        path:
          description: The path that was removed.
          type: string
      required:
      - deleted
      - path
    DeletedTaskFile:
      description: Confirmation naming the file that was removed.
      type: object
      properties:
        deleted:
          description: Whether the file was removed.
          type: boolean
        path:
          description: Absent on the API's no-result fallback
          type: string
      required:
      - deleted
    DirListing:
      description: One page of a source or knowledge directory. A listing returns a single page, so `offset` is 0 and `next_offset` is null; `limit` echoes the request rather than being applied.
      type: object
      properties:
        entries:
          description: The directory's immediate children.
          type: array
          items:
            description: One file or directory.
            type: object
            properties:
              name:
                description: Entry name, not a full path.
                type: string
              kind:
                description: Whether the entry is a file or a directory.
                x-enum:
                - dir
                - file
                type: string
              size:
                description: Byte size. 0 for a directory.
                type: integer
                format: int64
              mtime:
                description: RFC3339 last-modified, or empty when the store reports none
                type: string
            required:
            - name
            - kind
            - size
            - mtime
        total:
          description: Entries in this directory.
          type: integer
          format: int64
        offset:
          description: Echoes the request.
          type: integer
          format: int64
        limit:
          description: Echoes the request.
          type: integer
          format: int64
        next_offset:
          nullable: true
          description: Always null — a listing returns one page.
          type: integer
          format: int64
      required:
      - entries
      - total
      - offset
      - limit
    EdgeType:
      description: One typed, directed relationship between artifact types. `name`, `from`, and `to` are required of a written manifest; a read echoes a stored document that lacks one rather than failing.
      type: object
      properties:
        name:
          description: What the relationship is called, e.g. `mentions`.
          type: string
          maxLength: 64
        from:
          description: Source artifact-type name. May equal `to` for a self-referential edge.
          type: string
          maxLength: 64
        to:
          description: Target artifact-type name
          type: string
          maxLength: 64
        description:
          description: What the relationship means. Steers the extraction that finds it.
          type: string
          maxLength: 512
        attributes:
          description: Extra properties recorded on each edge, e.g. `count`.
          type: array
          items:
            description: One attribute name.
            type: string
            maxLength: 64
          maxItems: 16
      required:
      - name
      - from
      - to
    Error:
      description: The error envelope every non-2xx response uses.
      type: object
      properties:
        message:
          description: Human-readable explanation. Not stable — branch on `code`, not on this.
          type: string
        code:
          description: 'Stable machine-readable code, present only on errors a client must branch on. '
          x-enum:
          - unsupported_api_version
          - preview_not_enabled
          - preview_file_limit
          - preview_byte_limit
          - workspace_host_required
          - workspace_not_found
          type: string
      required:
      - message
    ErrorOutput:
      title: API-written failure
      description: What the API itself writes when a runtime reports a failure without an output of its own. Carries no `status` or `state` key.
      type: object
      properties:
        error:
          description: What went wrong.
          type: string
      required:
      - error
    ExploreContextRequest:
      description: Optional guidance for the proposal. Body may be omitted.
      type: object
      properties:
        guide:
          description: High-level guidance to steer the proposal
          type: string
        pinecone_api_key:
          description: Task-token override; normally not needed
          type: string
    ExploreInput:
      title: Explore
      description: What an explore run was started with.
      type: object
      properties:
        guide:
          description: Guidance the proposal was steered with. Empty when none was given.
          type: string
        trigger:
          description: What started the run, e.g. `manual`.
          type: string
      required:
      - guide
      - trigger
    ExploreOutput:
      title: Explore
      description: What an explore run proposed. Persists nothing — apply it by writing the manifest and forcing a curate.
      type: object
      properties:
        status:
          description: How the run ended.
          type: string
        matches:
          description: Validated template recommendations; unknown or low-confidence proposals are dropped upstream.
          type: array
          items:
            $ref: '#/components/schemas/TemplateMatch'
        none:
          description: True when no template fit
          type: boolean
        guide:
          description: The guidance the proposal was steered with, echoed back.
          type: string
        models:
          description: Tier → resolved model id.
          type: object
          additionalProperties:
            description: The model id the tier resolved to.
            type: string
        unknown_models:
          description: Model selections dropped as unknown before dispatch, so a caller whose pin was silently ignored can see it. Absent when nothing was dropped.
          type: array
          items:
            description: A requested model id or tier name the project's catalog does not carry.
            type: string
        usage:
          $ref: '#/components/schemas/ChatUsage'
      required:
      - status
      - matches
      - none
      - guide
      - models
      - usage
    FileBytes:
      description: The file bytes.
      type: string
      format: binary
    FileStats:
      description: Counts over a whole tree.
      type: object
      properties:
        file_count:
          description: Files in the tree.
          type: integer
          format: int64
        dir_count:
          description: Directories in the tree. Counts the ancestor prefixes of the stored objects, so a store with no standalone directories still reports one per level that holds a file.
          type: integer
          format: int64
        total_size:
          description: Summed byte size of every file.
          type: integer
          format: int64
      required:
      - file_count
      - dir_count
      - total_size
    GlossaryEntry:
      description: One term read verbatim out of a source by a `glossary`-kind artifact type.
      type: object
      properties:
        type:
          description: Artifact-type name.
          type: string
        name:
          description: The term.
          type: string
        clause:
          description: The source text defining it.
          type: string
      required:
      - type
      - name
      - clause
    GroomInput:
      title: Groom
      description: What a groom run was started with.
      type: object
      properties:
        budget:
          description: Cap on fact batches the run consolidates.
          type: integer
        groom_timeout_seconds:
          description: Runtime budget for the whole groom.
          type: integer
          format: int64
        models:
          description: Tier names or catalog ids, in preference order.
          type: array
          items:
            description: A tier name or catalog id.
            type: string
    GroomMetricsOutput:
      title: Groom
      description: What a groom run consolidated. Groom is to a work context what curate is to a search context — it distills facts out of accumulated work traces into artifacts.
      type: object
      properties:
        status:
          description: How the run ended.
          type: string
        budget:
          description: Fact batches the run was allowed to consume.
          type: integer
          format: int64
        batches_staged:
          description: Batches available to consume.
          type: integer
          format: int64
        batches_consumed:
          description: Batches actually consumed, capped by `budget`.
          type: integer
          format: int64
        facts_distilled:
          description: Facts extracted from the consumed batches.
          type: integer
          format: int64
        facts_added:
          description: Distilled facts that were new.
          type: integer
          format: int64
        facts_merged:
          description: Distilled facts folded into a fact already held.
          type: integer
          format: int64
        facts_dropped_untyped:
          description: Facts discarded because they matched no declared artifact type.
          type: integer
          format: int64
        edges_added:
          description: New relationships recorded between artifacts.
          type: integer
          format: int64
        artifacts_pruned:
          description: Artifacts removed as superseded.
          type: integer
          format: int64
        artifact_files_written:
          description: How many were written.
          type: integer
          format: int64
        artifact_files_deleted:
          description: How many were removed.
          type: integer
          format: int64
        artifact_count:
          description: Artifacts the context holds after the run.
          type: integer
          format: int64
        artifact_bytes:
          description: Total artifact size after the run.
          type: integer
          format: int64
        duration_ms:
          description: Wall time for the groom.
          type: integer
          format: int64
      required:
      - status
      - budget
      - batches_staged
      - batches_consumed
      - facts_distilled
      - facts_added
      - facts_merged
      - facts_dropped_untyped
      - edges_added
      - artifacts_pruned
      - artifact_files_written
      - artifact_files_deleted
      - artifact_count
      - artifact_bytes
      - duration_ms
    IdentityResponse:
      description: The caller and the project the credential names.
      type: object
      properties:
        user:
          description: The authenticated principal — a user email, or an API-key id for key auth.
          type: string
        project_id:
          description: The Pinecone project the session is scoped to.
          type: string
        project_name:
          nullable: true
          description: Null when the token still names a project whose row is gone.
          type: string
        workspace_name:
          nullable: true
          description: The workspace this host serves; null off a workspace-enabled cluster.
          type: string
        org_id:
          nullable: true
          description: Owning Pinecone organization; null off a workspace-enabled cluster.
          type: string
      required:
      - user
      - project_id
      - project_name
      - workspace_name
      - org_id
    ImportContextSourcesRequest:
      description: Which connector items to pull, and where to land them.
      type: object
      properties:
        connector_id:
          description: The linked connector to import from.
          type: string
        folder:
          description: Connector folder id to import
          type: string
        files:
          description: Connector file ids to import
          type: array
          items:
            description: A connector file id.
            type: string
        item_type:
          description: Whether `folder` or `files` selects the sources.
          default: folder
          x-enum:
          - folder
          - file
          type: string
        path:
          description: Subdirectory under the source tree (default uploads)
          type: string
      required:
      - connector_id
    ImportInput:
      title: Import
      description: One of three disjoint shapes, discriminated by which of `connector_id` / `url` / `raw_archive_key` is present.
      anyOf:
      - title: Connector import
        description: Sources pulled from a linked project connector.
        type: object
        properties:
          provider:
            description: The connector's provider, e.g. `box`.
            type: string
          connector_id:
            description: The linked connector the sources came from.
            type: string
          folder:
            nullable: true
            description: Connector folder imported. Null on a file-list import.
            type: string
          item_type:
            description: Whether `folder` or `files` selected the sources.
            x-enum:
            - folder
            - file
            type: string
          files:
            description: Connector file ids imported. Empty on a folder import.
            type: array
            items:
              description: A connector file id.
              type: string
          path:
            description: Subdirectory under the source tree the import landed in.
            type: string
          limits:
            $ref: '#/components/schemas/ImportLimits'
        required:
        - provider
        - connector_id
        - item_type
        - files
        - path
      - title: Public-repo import
        description: Sources fetched from a public URL.
        type: object
        properties:
          provider:
            description: The public-source provider, e.g. `github`.
            type: string
          url:
            description: The public repository or archive fetched.
            type: string
          path:
            description: Subdirectory under the source tree the import landed in.
            type: string
          limits:
            $ref: '#/components/schemas/ImportLimits'
        required:
        - provider
        - url
        - path
      - title: Archive upload
        description: Sources expanded from an uploaded archive.
        type: object
        properties:
          raw_archive_key:
            description: Staging key under the source bucket's `_inbox/` prefix
            type: string
          path:
            description: Subdirectory under the source tree the import landed in.
            type: string
          limits:
            $ref: '#/components/schemas/ImportLimits'
        required:
        - raw_archive_key
        - path
    ImportLimits:
      description: The caps the import ran under.
      type: object
      properties:
        allow_archives:
          description: Whether the run was permitted to expand archives.
          type: boolean
        allowed_extensions:
          description: File extensions the run was allowed to ingest.
          type: array
          items:
            description: One permitted file extension.
            type: string
        remaining_files:
          description: Files left under the context's file cap when the run started.
          type: integer
          format: int64
        remaining_bytes:
          description: Bytes left under the context's byte cap when the run started.
          type: integer
          format: int64
        max_file_bytes:
          description: Upper bound on one stored object.
          type: integer
          format: int64
    ImportManifestEntry:
      description: One ingest record — what happened to a single source the import saw.
      type: object
      properties:
        src:
          description: The record at the provider.
          type: string
        action:
          description: What happened to the record. `parsed` converted the file to text, `copied` took it as-is, `extracted` expanded an archive.
          x-enum:
          - parsed
          - copied
          - extracted
          - skipped
          - failed
          type: string
        out:
          description: Empty exactly when nothing was written
          type: array
          items:
            description: A path written into the source tree.
            type: string
        fmt:
          description: Format the ingester recognized.
          type: string
        reason:
          description: Why it was skipped or how it failed. Empty on success.
          type: string
        bytes:
          description: Bytes written for this record.
          type: integer
          format: int64
      required:
      - src
      - action
      - out
      - fmt
      - reason
      - bytes
    ImportOutput:
      title: Import
      description: What an import staged. Staging only — the sources are not indexed until a curate runs.
      type: object
      properties:
        status:
          description: How the run ended.
          type: string
        imported_items:
          description: Records pulled from the provider.
          type: integer
          format: int64
        output_files:
          description: Files written into the source tree. Higher than `imported_items` when archives or multi-page documents expanded.
          type: integer
          format: int64
        failed:
          description: Records that could not be ingested.
          type: integer
          format: int64
        skipped:
          description: Records passed over, e.g. an unsupported extension or a cap already reached.
          type: integer
          format: int64
        skipped_items:
          description: Bounded sample of the skipped records
          type: array
          items:
            $ref: '#/components/schemas/ImportManifestEntry'
        manifest_sample:
          description: Bounded sample of the records that produced output
          type: array
          items:
            $ref: '#/components/schemas/ImportManifestEntry'
        manifest_truncated:
          description: Whether either sample was cut
          type: boolean
        manifest_file:
          description: Where the full manifest was written
          type: string
        manifest_object:
          description: Object-store key of the full manifest
          type: string
      required:
      - status
      - imported_items
      - output_files
      - failed
      - skipped
      - skipped_items
      - manifest_sample
      - manifest_truncated
      - manifest_file
    LiveFileListing:
      title: Live
      description: Read from the running container, so entries carry a POSIX `mode` and may be symlinks — neither of which the archived branch has. Pages by bytes as well as count, so it can stop short of `limit`.
      type: object
      properties:
        entries:
          description: The directory's immediate children.
          type: array
          items:
            description: One entry as the container reported it.
            type: object
            properties:
              name:
                description: Entry name, not a full path.
                type: string
              kind:
                description: 'Entry kind: `file`, `dir` or `symlink` when the stat is recognized, and the raw stat word otherwise.'
                type: string
              size:
                description: Byte size. 0 for a directory.
                type: integer
                format: int64
              mode:
                description: POSIX permission bits, as reported by the container.
                type: string
              mtime:
                description: Last-modified time as the container reported it.
                type: string
            required:
            - name
            - kind
            - size
            - mode
            - mtime
        total:
          description: Entries in the directory.
          type: integer
          format: int64
        offset:
          description: Where this page starts.
          type: integer
          format: int64
        limit:
          description: Maximum entries the page was allowed.
          type: integer
          format: int64
        next_offset:
          nullable: true
          description: Where the next page starts. Absent until the container is running; null once it is and the page is the last.
          type: integer
          format: int64
      required:
      - entries
      - total
      - offset
      - limit
    LoginRequest:
      description: The key to exchange. May be omitted where the deployment supplies its own.
      type: object
      properties:
        api_key:
          description: Pinecone API key. Optional — when absent, the server falls back to its configured key (managed) or validates the seeded credential (BYOC).
          type: string
    LoginResponse:
      description: The session token and the identity it authenticates.
      type: object
      properties:
        token:
          description: 'Session JWT. Send it as `Authorization: Bearer <token>` on every other call.'
          type: string
        principal:
          description: Who the token authenticates — a user email, or the id of the API key it was exchanged for.
          type: string
        project_id:
          description: The Pinecone project the token is scoped to.
          type: string
        project_name:
          description: Human-readable label for the project the token is scoped to.
          type: string
      required:
      - token
      - principal
      - project_id
      - project_name
    Manifest:
      description: 'The document that drives curate and search. Sparse: every field is optional and an omitted one falls back to its default, so absent fields are omitted rather than nulled. A change reaches the index on the next curate; rebuilding what is already indexed needs a forced one.'
      type: object
      properties:
        curate:
          $ref: '#/components/schemas/CurateManifest'
        optimize:
          $ref: '#/components/schemas/OptimizeManifest'
        search:
          $ref: '#/components/schemas/SearchManifest'
    ManifestSuggestion:
      description: Outcome of the last explore run, pinned to the context row. A proposal only — apply it by writing the manifest and forcing a curate.
      type: object
      properties:
        matches:
          description: Proposed templates, best fit first.
          type: array
          items:
            $ref: '#/components/schemas/TemplateMatch'
        none:
          description: True when no template fit
          type: boolean
        explored_at:
          description: When the run produced this proposal.
          type: string
          format: date-time
        task_id:
          description: The explore task that produced it.
          type: string
      required:
      - matches
      - none
      - explored_at
    ManifestTemplate:
      description: One built-in starting point for a context manifest.
      type: object
      properties:
        id:
          description: Stable template id, as matched by `explore` and named by `default_id`.
          type: string
        label:
          description: Short display name.
          type: string
        description:
          description: What corpus shape the template is built for.
          type: string
        when_to_use:
          description: Guidance for picking this template over its neighbours.
          type: string
        default:
          description: Set on the catalog's default template, and absent on every other.
          type: boolean
        sample_questions:
          description: Questions a corpus curated under this template should answer.
          type: array
          items:
            description: One example question.
            type: string
        manifest:
          description: The manifest document the template seeds a context with.
          allOf:
          - $ref: '#/components/schemas/Manifest'
      required:
      - id
      - label
      - description
      - when_to_use
      - sample_questions
      - manifest
    ManifestTemplateCatalog:
      description: The built-in manifest templates, baked into the build rather than stored per project.
      type: object
      properties:
        version:
          description: Catalog revision. Bumped when the baked templates change.
          type: integer
          format: int64
        default_id:
          description: The `id` of the template applied when a caller names none.
          type: string
        templates:
          description: The templates, in display order.
          type: array
          items:
            $ref: '#/components/schemas/ManifestTemplate'
      required:
      - version
      - default_id
      - templates
    ModelCatalog:
      description: The models this deployment can run, and the defaults it resolves.
      type: object
      properties:
        default:
          description: Model id used when `model` is omitted
          type: string
        models:
          description: Every catalog entry, selectable or not.
          type: array
          items:
            description: One catalog entry.
            type: object
            properties:
              id:
                description: Catalog model id, passed as `model` on `POST /query`. Some carry a vendor prefix and some do not, so treat it as opaque.
                type: string
              label:
                description: Display name.
                type: string
              provider:
                description: Who serves the model.
                type: string
              available:
                description: Whether the model can be selected. An unavailable one is rejected with `400`.
                type: boolean
            required:
            - id
            - label
            - provider
            - available
        tiers:
          description: Tier (`lite`/`standard`/`pro`) → resolved model id. A tier name is accepted anywhere a model id is, so a caller can ask for `standard` and let the deployment choose.
          type: object
          additionalProperties:
            description: The model id the tier resolves to.
            type: string
        phase_defaults:
          description: Workflow phase → the model id or tier name that phase defaults to.
          type: object
          additionalProperties:
            description: The model id or tier the phase defaults to.
            type: string
        supported_curate_models:
          description: Model ids the curate runtime accepts — a subset of the catalog, since curate reads the whole corpus and is priced accordingly.
          type: array
          items:
            description: One entry the curate runtime accepts.
            type: string
        query_defaults:
          description: The per-turn harness values a turn runs with when the request sets none.
          allOf:
          - $ref: '#/components/schemas/QueryDefaults'
      required:
      - default
      - models
      - tiers
      - phase_defaults
      - supported_curate_models
      - query_defaults
    ModelUsage:
      description: Per-model chat-seam counts; both usage roll-ups write every key.
      type: object
      properties:
        tier:
          description: Which tier resolved to this model, so a tier fallback is visible.
          type: string
        prompt_tokens:
          description: Input tokens billed to this model.
          type: integer
          format: int64
        completion_tokens:
          description: Output tokens billed to this model.
          type: integer
          format: int64
        cache_read_tokens:
          description: Input served without re-billing.
          type: integer
          format: int64
        cache_write_tokens:
          description: Prompt tokens written into cache.
          type: integer
          format: int64
        total_tokens:
          description: Input plus output tokens for this model.
          type: integer
          format: int64
      required:
      - tier
      - prompt_tokens
      - completion_tokens
      - cache_read_tokens
      - cache_write_tokens
      - total_tokens
    NullableManifest:
      nullable: true
      description: The pinned manifest, or `null` when the context pins none.
      type: object
      allOf:
      - description: 'The document that drives curate and search. Sparse: every field is optional and an omitted one falls back to its default, so absent fields are omitted rather than nulled. A change reaches the index on the next curate; rebuilding what is already indexed needs a forced one.'
        x-component-name: Manifest
        type: object
        properties:
          curate:
            description: What curate builds out of the sources — the chunk leg, the artifact leg, or both.
            x-component-name: CurateManifest
            type: object
            properties:
              chunks:
                description: The chunk leg — sources split into passages, embedded for semantic search and optionally indexed for keyword search.
                x-component-name: ChunksConfig
                type: object
                properties:
                  enabled:
                    description: Whether curate builds the chunk leg at all.
                    default: true
                    type: boolean
                  embedding_model:
                    description: Model that embeds the chunks.
                    default: multilingual-e5-large
                    type: string
                    maxLength: 128
                  chunking:
                    description: How a source is cut into chunks.
                    x-component-name: ChunkingConfig
                    type: object
                    properties:
                      strategy:
                        description: Which structure the splitter cuts on — markdown headings, fixed-size windows, HTML elements, CSV rows, or code syntax. Pick the one that matches the corpus.
                        default: markdown_heading
                        x-enum:
                        - markdown_heading
                        - sliding_window
                        - html
                        - csv
                        - code
                        type: string
                      target_size:
                        description: Chunk size the splitter aims for, in tokens. Smaller chunks retrieve more precisely; larger ones carry more surrounding context.
                        default: 512
                        type: integer
                        minimum: 64
                        maximum: 4096
                      overlap:
                        description: Tokens each chunk repeats from its predecessor, so a passage split across a boundary is still retrievable whole.
                        default: 64
                        type: integer
                        minimum: 0
                        maximum: 1024
                      respect_sections:
                        description: Never cut across a section boundary, even when that leaves a chunk short of `target_size`.
                        default: true
                        type: boolean
                  keyword:
                    description: The lexical index built alongside the vectors, for exact-term matching.
                    type: object
                    properties:
                      enabled:
                        description: Whether the lexical index is built.
                        default: true
                        type: boolean
              artifacts:
                description: 'The artifact leg: knowledge an LLM distills out of the sources, as prose files or database rows. Off by default.'
                x-component-name: ArtifactsConfig
                type: object
                properties:
                  enabled:
                    description: Whether curate extracts artifacts at all.
                    default: false
                    type: boolean
                  artifact_model:
                    description: Model tier that does the extraction. `standard` reads more carefully at a higher token cost.
                    default: lite
                    x-enum:
                    - standard
                    - lite
                    type: string
                  artifact_types:
                    description: What kinds of artifact to extract. Nothing is extracted until at least one is declared.
                    type: array
                    items:
                      description: One kind of artifact to extract. `name` is required of a written manifest; a read echoes a stored document that lacks one rather than failing.
                      x-component-name: ArtifactType
                      type: object
                      properties:
                        name:
                          description: What the type is called. Edge endpoints reference it, and a sqlite type's table is named after it.
                          type: string
                          maxLength: 64
                        kind:
                          description: What the artifact represents, which selects the extraction prompt. `glossary` is the exception — it reads the headings named in `sections` deterministically, with no LLM call.
                          default: topic
                          x-enum:
                          - summary
                          - topic
                          - entity
                          - event
                          - doc
                          - page
                          - glossary
                          type: string
                        scope:
                          description: How widely the extraction reaches. `document` extracts one artifact per source; `corpus` reduces mentions from across every source into one artifact per subject.
                          default: corpus
                          x-enum:
                          - document
                          - corpus
                          type: string
                        icon:
                          description: Symbol to display beside artifacts of this kind.
                          type: string
                          maxLength: 64
                        description:
                          description: What this type should capture. Goes into the extraction prompt, so it steers the result.
                          type: string
                          maxLength: 512
                        coverage:
                          description: Topics the extraction is told to address wherever the source speaks to them.
                          type: array
                          items:
                            description: One topic the extraction should address.
                            type: string
                            maxLength: 128
                          maxItems: 32
                        sections:
                          description: Exact section headings a `glossary`-kind type reads verbatim. Ignored by every other kind.
                          type: array
                          items:
                            description: One exact section heading to read.
                            type: string
                            maxLength: 128
                          maxItems: 64
                        min_doc_count:
                          description: Overrides the manifest-level `min_doc_count` for this type.
                          default: 1
                          type: integer
                          minimum: 1
                          maximum: 64
                        format:
                          description: Where the artifacts of this type are written — `markdown` a prose file each, `sqlite` rows in the context's structured database.
                          default: markdown
                          x-enum:
                          - markdown
                          - sqlite
                          type: string
                        columns:
                          description: Table schema for a `sqlite`-format type. Ignored for `markdown`. Two names that normalize to the same column collide, and the first declaration wins.
                          type: array
                          items:
                            description: One column of the type's table.
                            type: object
                            properties:
                              name:
                                description: Column name.
                                type: string
                                maxLength: 64
                              type:
                                description: SQLite column affinity.
                                default: TEXT
                                x-enum:
                                - TEXT
                                - INTEGER
                                - REAL
                                - NUMERIC
                                type: string
                              description:
                                description: What the column holds. Steers the extraction that fills it.
                                type: string
                                maxLength: 256
                            required:
                            - name
                          maxItems: 64
                        natural_key:
                          description: Columns that identify a row uniquely, so re-curating a source upserts its rows rather than duplicating them. `sqlite`-format types only.
                          type: array
                          items:
                            description: One column of the upsert key.
                            type: string
                            maxLength: 64
                          maxItems: 16
                      required:
                      - name
                    maxItems: 32
                  edge_types:
                    description: Typed, directed relationships between artifact types, which turn the artifacts into a graph the agent can traverse.
                    type: array
                    items:
                      description: One typed, directed relationship between artifact types. `name`, `from`, and `to` are required of a written manifest; a read echoes a stored document that lacks one rather than failing.
                      x-component-name: EdgeType
                      type: object
                      properties:
                        name:
                          description: What the relationship is called, e.g. `mentions`.
                          type: string
                          maxLength: 64
                        from:
                          description: Source artifact-type name. May equal `to` for a self-referential edge.
                          type: string
                          maxLength: 64
                        to:
                          description: Target artifact-type name
                          type: string
                          maxLength: 64
                        description:
                          description: What the relationship means. Steers the extraction that finds it.
                          type: string
                          maxLength: 512
                        attributes:
                          description: Extra properties recorded on each edge, e.g. `count`.
                          type: array
                          items:
                            description: One attribute name.
                            type: string
                            maxLength: 64
                          maxItems: 16
                      required:
                      - name
                      - from
                      - to
                    maxItems: 32
                  min_doc_count:
                    description: How many source documents must mention a corpus-scoped subject before it earns an artifact. Raise it to suppress one-off mentions. An artifact type may override it.
                    default: 1
                    type: integer
                    minimum: 1
                    maximum: 64
                  max_tokens:
                    description: Output cap for one extracted artifact, in tokens.
                    default: 1500
                    type: integer
                    minimum: 128
                    maximum: 8192
                  max_doc_chars:
                    description: Input cap for one extraction call, in characters. With windowing off this also caps how much of a source is read at all; everything beyond it is dropped.
                    default: 60000
                    type: integer
                    minimum: 1000
                    maximum: 2000000
                  extraction_window_chars:
                    description: Window size for walking a long source across several extraction calls, so its back half is covered rather than dropped. `0` opts out and reads only the head, up to `max_doc_chars`.
                    default: 0
                    type: integer
                    minimum: 0
                    maximum: 1000000
                  mention_max_chars:
                    description: Cap on one recorded mention — what a single document says about the subject — in characters.
                    default: 400
                    type: integer
                    minimum: 100
                    maximum: 4000
                  max_mentions_per_artifact:
                    description: How many mentions are fed into the pass that reduces them into one corpus-wide artifact.
                    default: 40
                    type: integer
                    minimum: 1
                    maximum: 500
                  mention_context_chars:
                    description: Cap on those mentions once concatenated, in characters. Applied after `max_mentions_per_artifact`.
                    default: 8000
                    type: integer
                    minimum: 1000
                    maximum: 100000
                  max_artifacts_per_type:
                    description: How many artifacts one type may produce. Omit for no cap.
                    default: 10000
                    type: integer
                    minimum: 1
                    maximum: 10000
          optimize:
            description: 'The scheduled self-tuning loop: it clusters the queries that answered badly and tries candidate manifests against an ephemeral index until one reproduces the recorded answers.'
            x-component-name: OptimizeManifest
            type: object
            properties:
              schedule:
                description: Cron expression the tuning loop runs on.
                default: 0 * * * *
                type: string
                maxLength: 128
              latency_threshold_ms:
                description: A query slower than this counts as a problem worth tuning for, as does any query that fell back from artifacts to chunks. `0` disables the latency test, leaving only fallback.
                default: 60000
                type: integer
                minimum: 0
                maximum: 600000
              min_group_size:
                description: How many near-duplicate problem queries must cluster together before the loop tunes for them. Keeps a one-off slow query from triggering a manifest change.
                default: 2
                type: integer
                minimum: 1
                maximum: 100
              eval_pass_rate_threshold:
                description: Fraction of eval queries a candidate manifest must answer correctly to be considered ready. `1` demands all of them.
                default: 1
                type: number
                format: double
                minimum: 0.0
                maximum: 1.0
              max_iterations:
                description: How many candidate manifests the loop tries before stopping with its best.
                default: 20
                type: integer
                minimum: 1
                maximum: 100
          search:
            description: Standing instructions for the query runtime, pinned on the context rather than sent per turn.
            x-component-name: SearchManifest
            type: object
            properties:
              instructions:
                description: The context's default system prompt, applied to every turn in scope. A session's own `system_prompt` appends to it rather than replacing it.
                type: string
    OptimizeContextRequest:
      description: Optional overrides for the tuning loop. `{}` is valid and is a no-op.
      type: object
      properties:
        eval_pass_rate_threshold:
          description: Pass rate a candidate manifest must clear to count as ready.
          type: number
          format: double
        retrieval_p90_latency_ms:
          description: The p90 latency bar a candidate must stay under.
          type: integer
          format: int64
        optimize_timeout_seconds:
          description: Default 7200
          type: integer
          format: int64
        max_iterations:
          description: Default 20
          type: integer
        max_tool_turns:
          description: Default 200
          type: integer
        models:
          description: Model-id overrides passed to the optimize runtime
          type: array
          items:
            description: A tier name or catalog id.
            type: string
        candidate_queries:
          description: Recent query records to tune toward (absent = no-op)
          type: array
          items:
            $ref: '#/components/schemas/CandidateQuery'
        pinecone_api_key:
          description: Task-token override; normally not needed
          type: string
    OptimizeInput:
      title: Optimize
      description: Only the keys the trigger request supplied are written, so an input with no keys is a valid no-op optimize.
      type: object
      properties:
        candidate_queries:
          description: The queries the run tunes toward. Absent makes the run a no-op.
          type: array
          items:
            $ref: '#/components/schemas/CandidateQuery'
        eval_pass_rate_threshold:
          description: Pass rate an iteration must clear to count as ready.
          type: number
          format: double
        retrieval_p90_latency_ms:
          description: The p90 latency bar an iteration must stay under.
          type: integer
          format: int64
        optimize_timeout_seconds:
          description: Runtime budget for the whole optimize.
          type: integer
          format: int64
        max_tool_turns:
          description: Cap on tool-loop turns per eval query.
          type: integer
        max_iterations:
          description: Cap on candidate manifests tried.
          type: integer
        models:
          description: Tier names or catalog ids, in preference order.
          type: array
          items:
            description: A tier name or catalog id.
            type: string
    OptimizeManifest:
      description: 'The scheduled self-tuning loop: it clusters the queries that answered badly and tries candidate manifests against an ephemeral index until one reproduces the recorded answers.'
      type: object
      properties:
        schedule:
          description: Cron expression the tuning loop runs on.
          default: 0 * * * *
          type: string
          maxLength: 128
        latency_threshold_ms:
          description: A query slower than this counts as a problem worth tuning for, as does any query that fell back from artifacts to chunks. `0` disables the latency test, leaving only fallback.
          default: 60000
          type: integer
          minimum: 0
          maximum: 600000
        min_group_size:
          description: How many near-duplicate problem queries must cluster together before the loop tunes for them. Keeps a one-off slow query from triggering a manifest change.
          default: 2
          type: integer
          minimum: 1
          maximum: 100
        eval_pass_rate_threshold:
          description: Fraction of eval queries a candidate manifest must answer correctly to be considered ready. `1` demands all of them.
          default: 1
          type: number
          format: double
          minimum: 0.0
          maximum: 1.0
        max_iterations:
          description: How many candidate manifests the loop tries before stopping with its best.
          default: 20
          type: integer
          minimum: 1
          maximum: 100
    OptimizeNoopOutput:
      title: Optimize no-op
      description: Too few candidate queries or problems to tune from.
      type: object
      properties:
        status:
          description: How the run ended.
          type: string
        reason:
          description: Which gate the run stopped at.
          type: string
        candidate_queries:
          description: Candidate queries the run was given.
          type: integer
          format: int64
        problems:
          description: How many of those counted as problems worth tuning for.
          type: integer
          format: int64
      required:
      - status
      - reason
      - candidate_queries
      - problems
    OptimizeResultOutput:
      title: Optimize result
      description: What the tuning loop settled on.
      type: object
      properties:
        status:
          description: Set to `ready` only when the best iteration cleared both the pass-rate and latency bars.
          type: string
        best_score:
          description: Eval pass rate the best iteration scored, 0–1.
          type: number
          format: double
        best_iteration:
          description: Which iteration scored it.
          type: integer
          format: int64
        best_latency_ok:
          description: Whether that iteration also stayed under the latency bar.
          type: boolean
        total_iterations:
          description: Candidate manifests tried.
          type: integer
          format: int64
        pass_rate_threshold:
          description: The pass-rate bar the run measured against.
          type: number
          format: double
        p90_latency_limit_ms:
          nullable: true
          description: The p90 latency bar. Null when latency was not gated.
          type: number
          format: double
        elapsed_seconds:
          description: Wall time for the whole loop.
          type: number
          format: double
        usage:
          $ref: '#/components/schemas/ChatUsage'
        models:
          description: Tier → resolved model id.
          type: object
          additionalProperties:
            description: The model id the tier resolved to.
            type: string
        unknown_models:
          description: Model selections dropped as unknown before dispatch, so a caller whose pin was silently ignored can see it. Absent when nothing was dropped.
          type: array
          items:
            description: A requested model id or tier name the project's catalog does not carry.
            type: string
        manifest:
          description: The tuned manifest persisted onto the context when the task completes.
          allOf:
          - $ref: '#/components/schemas/Manifest'
        changed_legs:
          description: Which manifest legs the tuning changed, so a re-curate can be scoped to them.
          type: array
          items:
            description: A manifest leg the tuning changed.
            type: string
      required:
      - status
      - best_score
      - best_iteration
      - best_latency_ok
      - total_iterations
      - pass_rate_threshold
      - p90_latency_limit_ms
      - elapsed_seconds
      - usage
      - models
      - manifest
      - changed_legs
    PackCompletedOutput:
      title: Pack completed
      description: The archive is written. Download it from `GET /tasks/{id}/files/read/{pack_filename}`.
      type: object
      properties:
        state:
          description: Which stage of the pack this report describes.
          type: string
        pack_filename:
          description: Name of the written archive, `<slug>.context.zip`.
          type: string
        pack_size:
          description: Byte size of the archive.
          type: integer
          format: int64
        sources_files:
          description: How many corpus documents went into the archive.
          type: integer
          format: int64
        knowledge_files:
          description: How many curated documents went into the archive.
          type: integer
          format: int64
        traces_included:
          description: Whether query traces were included.
          type: boolean
        traces_files:
          description: Trace blobs packed.
          type: integer
          format: int64
        corpus_groups_included:
          description: Corpus groups carried over from the curation ledger.
          type: integer
          format: int64
        started_at:
          description: When the pack started.
          type: string
        completed_at:
          description: When the pack finished.
          type: string
        details:
          $ref: '#/components/schemas/PackDetails'
      required:
      - state
      - pack_filename
      - pack_size
      - sources_files
      - knowledge_files
      - traces_included
      - traces_files
      - corpus_groups_included
      - started_at
      - completed_at
      - details
    PackDetails:
      nullable: true
      description: LLM-written corpus summary, echoed from the pack's `details.json`. Null when enrichment was skipped or failed.
      type: object
      properties:
        description:
          description: Prose summary of what the packed corpus covers.
          type: string
        sample_queries:
          description: Example questions the packed corpus can answer.
          type: array
          items:
            description: One example question.
            type: string
      required:
      - description
      - sample_queries
    PackInput:
      title: Pack
      description: What a pack run was started with.
      type: object
      properties:
        include_traces:
          description: Whether query traces were packed alongside sources and knowledge.
          type: boolean
        slug:
          description: Slug of the packed context; names the output archive.
          type: string
        context_id:
          description: The context that was packed.
          type: string
      required:
      - include_traces
      - slug
      - context_id
    PackRunningOutput:
      title: Pack running
      description: 'A pack''s progress: the initial claim, the enrichment pass, then periodic write progress, each adding to what came before. `state` is `running` on all of them, so key presence is what tells them apart.'
      type: object
      properties:
        state:
          description: Always `running`. Which report this is shows in the keys it carries, not here.
          x-enum:
          - running
          type: string
        slug:
          description: Slug of the context being packed.
          type: string
        include_traces:
          description: Whether query traces are being packed. Absent on the write-progress report.
          type: boolean
        started_at:
          description: When the pack started. Absent on the write-progress report.
          type: string
        sources_total:
          description: Source files to be packed. Absent until the inventory is counted.
          type: integer
          format: int64
        knowledge_total:
          description: Curated knowledge files to be packed. Absent until the inventory is counted.
          type: integer
          format: int64
        traces_total:
          description: Trace blobs to be packed. Absent until the inventory is counted.
          type: integer
          format: int64
        bytes_collected:
          description: Bytes read so far. Absent until the inventory is counted.
          type: integer
          format: int64
        enriching:
          description: Present while the LLM writes the pack's summary.
          type: boolean
        files_written:
          description: Files written into the archive so far. Present only once writing has begun.
          type: integer
          format: int64
      required:
      - state
      - slug
    PointerEntry:
      description: One recorded mention — what a single source said about a subject, held until the corpus pass reduces every mention of that subject into one artifact.
      type: object
      properties:
        type:
          description: Artifact-type name
          type: string
        name:
          description: The subject mentioned.
          type: string
        mention:
          description: What this source says about it.
          type: string
        seq:
          description: Ordinal of the mention within the source.
          type: integer
      required:
      - type
      - name
    ProfileContextRequest:
      description: The manifest to estimate against. Body may be omitted.
      type: object
      properties:
        manifest:
          description: In-progress manifest to estimate against (default {})
          allOf:
          - $ref: '#/components/schemas/Manifest'
        pinecone_api_key:
          description: Task-token override; normally not needed
          type: string
    ProfileEmptyOutput:
      title: Profile empty
      description: The profile had nothing to sample — a context with no sources, or none the manifest covers.
      type: object
      properties:
        state:
          description: How the run ended.
          type: string
        reason:
          description: Why no estimate could be made.
          type: string
      required:
      - state
      - reason
    ProfileEstimateOutput:
      title: Profile estimate
      description: An estimate of what curating the candidate manifest would cost, extrapolated from a sample of the corpus. Persists nothing.
      type: object
      properties:
        state:
          description: How the run ended.
          type: string
        g:
          description: Estimated distinct-artifact count with its uncertainty band. This is what drives the cost estimate, since extraction cost scales with it.
          type: object
          properties:
            value:
              description: Point estimate of the distinct-artifact count.
              type: integer
              format: int64
            lo:
              description: Low end of the band.
              type: integer
              format: int64
            hi:
              description: High end of the band.
              type: integer
              format: int64
            method:
              description: The estimator the recurrence blend selected; `empty` on the no-sample path
              type: string
            recurrence:
              description: How often the same subject recurs across sampled documents. Drives which estimator is chosen.
              type: number
              format: double
            confidence:
              description: Qualitative confidence in the estimate.
              type: string
            note:
              description: Caveat on how to read the estimate.
              type: string
          required:
          - value
          - lo
          - hi
          - method
          - recurrence
          - confidence
          - note
        density:
          description: Measured on the sampling window, not the full curate read-depth.
          type: object
          properties:
            entities_per_doc:
              description: Mean distinct subjects found per sampled document.
              type: number
              format: double
            avg_doc_chars:
              description: Mean source length in characters.
              type: integer
              format: int64
          required:
          - entities_per_doc
          - avg_doc_chars
        cost:
          description: Estimated token and time cost of the curate, one estimate per model tier.
          type: object
          properties:
            by_tier:
              description: One estimate per model tier.
              type: object
              properties:
                lite:
                  $ref: '#/components/schemas/ProfileTierCost'
                standard:
                  $ref: '#/components/schemas/ProfileTierCost'
                pro:
                  $ref: '#/components/schemas/ProfileTierCost'
              required:
              - lite
              - standard
              - pro
            default_tier:
              description: The tier the context's current `artifact_model` resolves to
              type: string
          required:
          - by_tier
          - default_tier
        sampling:
          description: How much of the corpus the profile actually read. The estimate is extrapolated from this much, so a small `fraction` means a wide band.
          type: object
          properties:
            n_total:
              description: Sources in the corpus.
              type: integer
              format: int64
            n_sampled:
              description: Sources the profile read.
              type: integer
              format: int64
            fraction:
              description: The `n_sampled` count over `n_total`.
              type: number
              format: double
            wall_s:
              description: Seconds the sampling itself took.
              type: number
              format: double
          required:
          - n_total
          - n_sampled
          - fraction
          - wall_s
      required:
      - state
      - g
      - density
      - cost
      - sampling
    ProfileInput:
      title: Profile
      description: What a profile run was started with.
      type: object
      properties:
        manifest:
          description: The candidate manifest the run profiles, not a stored one.
          allOf:
          - $ref: '#/components/schemas/Manifest'
        trigger:
          description: What started the run, e.g. `manual`.
          type: string
      required:
      - manifest
      - trigger
    ProfileTierCost:
      description: What the curate would cost at one model tier.
      type: object
      properties:
        tokens:
          description: The `point` estimate sits at G's midpoint and splits into input/output; `lo`/`hi` are band totals.
          type: object
          properties:
            point:
              description: Estimate at the artifact count's midpoint.
              type: integer
              format: int64
            lo:
              description: Total at the low end of the band.
              type: integer
              format: int64
            hi:
              description: Total at the high end of the band.
              type: integer
              format: int64
            input:
              description: Input share of the point estimate.
              type: integer
              format: int64
            output:
              description: Output share of the point estimate.
              type: integer
              format: int64
          required:
          - point
          - lo
          - hi
          - input
          - output
        time_s:
          description: Estimated wall-clock band for the curate, in seconds.
          type: object
          properties:
            lo:
              description: Low end of the wall-clock band.
              type: integer
              format: int64
            hi:
              description: High end of the wall-clock band.
              type: integer
              format: int64
          required:
          - lo
          - hi
      required:
      - tokens
      - time_s
    Project:
      description: The Pinecone project every context, session, and task in this deployment belongs to.
      type: object
      properties:
        id:
          description: Pinecone project id.
          type: string
        name:
          description: Display name.
          type: string
        created_at:
          description: When the project was created.
          type: string
          format: date-time
        updated_at:
          description: When the project last changed.
          type: string
          format: date-time
      required:
      - id
      - name
      - created_at
      - updated_at
    ProjectTaskStats:
      description: Aggregate task counters for the whole project.
      type: object
      properties:
        tasks_total:
          description: Tasks the project has ever run.
          type: integer
        tasks_active:
          description: Tasks in a non-terminal state.
          type: integer
        tasks_completed:
          description: Tasks that finished successfully.
          type: integer
        tasks_cancelled:
          description: Runs stopped before they finished.
          type: integer
        tasks_by_state:
          description: Keyed by `TaskState`
          type: object
          additionalProperties:
            description: Tasks in that state.
            type: integer
        tasks_by_workflow:
          description: Keyed by `Workflow`
          type: object
          additionalProperties:
            description: Tasks of that workflow.
            type: integer
        captured_at:
          description: When the counters were read.
          type: string
          format: date-time
      required:
      - tasks_total
      - tasks_active
      - tasks_completed
      - tasks_cancelled
      - tasks_by_state
      - tasks_by_workflow
      - captured_at
    ProjectWithWorkspaces:
      description: The active project plus whether this deployment requires a workspace host.
      allOf:
      - $ref: '#/components/schemas/Project'
      - description: The workspace-gating flag added on top of the project row.
        type: object
        properties:
          workspaces_required:
            description: True on a workspace-enabled cluster, where requests must use the `wksp.*` workspace host rather than the account host.
            type: boolean
        required:
        - workspaces_required
    Query:
      title: Query turn
      description: One query turn. Read the answer from `output[].content[].text`.
      type: object
      properties:
        id:
          description: Turn id, `qry_<uuid>`.
          type: string
        object:
          description: Always `query`, so a caller can tell this document apart from a session.
          x-enum:
          - query
          type: string
        session_id:
          description: The session this turn belongs to. A turn that started a new one names it here.
          type: string
        model:
          nullable: true
          description: The model that actually answered. Null before the turn resolves one.
          type: string
        created:
          description: Unix seconds
          type: integer
          format: int64
        status:
          description: Where the turn is in its lifecycle.
          x-enum:
          - in_progress
          - completed
          - failed
          - cancelled
          type: string
        error:
          nullable: true
          description: Failure detail. Set on a `failed` turn.
          type: string
        previous_query_id:
          nullable: true
          description: The turn this one continues. Null on a session's first turn.
          type: string
        comparison:
          nullable: true
          description: The sibling turns of the same Compare run. Null on a normal single query.
          type: array
          items:
            $ref: '#/components/schemas/QueryComparisonMember'
        feedback:
          nullable: true
          description: Thumbs-up/down recorded on this turn. Null until a caller submits some.
          type: object
          properties:
            rating:
              description: Thumbs up or down.
              x-enum:
              - up
              - down
              type: string
            comment:
              nullable: true
              description: Free-text note. Null when none was given.
              type: string
        input:
          description: The stored message array (plain-text `content`).
          type: array
          items:
            description: One message in the turn.
            type: object
            properties:
              role:
                description: Who sent the message, e.g. `user`.
                type: string
              content:
                description: The message text.
                type: string
            required:
            - role
            - content
        output:
          description: 'Output items; assistant text is `{role, content:[{type: output_text, text}]}`'
          type: array
          items:
            description: One output item.
            type: object
            properties:
              role:
                description: Who produced it, e.g. `assistant`.
                type: string
              content:
                description: The item's content parts.
                type: array
                items:
                  description: One content part.
                  type: object
                  properties:
                    type:
                      description: Part kind. `output_text` carries the answer.
                      type: string
                    text:
                      description: The text of this part.
                      type: string
                  required:
                  - type
                  - text
            required:
            - role
            - content
        output_json:
          nullable: true
          description: Present when a shape was used, or on a retrieval-only turn
          type: object
          additionalProperties: true
        citations:
          description: What the answer was grounded in. Empty on a turn that cited nothing.
          type: array
          items:
            $ref: '#/components/schemas/Citation'
        max_steps:
          nullable: true
          description: The agentic tool-loop step cap this turn actually ran with, whether the request set it or the deployment default supplied it.
          type: integer
          format: int64
        thinking_level:
          nullable: true
          description: The thinking level this turn actually ran at. Null on the Claude-backed `search_cc`, which has no equivalent knob.
          type: string
        steps:
          description: The turn's reasoning steps, reduced from its `response.step` events.
          type: array
          items:
            $ref: '#/components/schemas/QueryStep'
        rollup:
          nullable: true
          description: End-of-turn counters. Null on a turn the runtime never closed.
          type: object
          allOf:
          - title: Response turn rollup
            description: A turn's end-of-turn counters. Served both as the stored `response.turn_rollup` event, which adds `type` and `query_id`, and as the trace blob's copy, which does not.
            x-component-name: TurnRollup
            type: object
            properties:
              type:
                description: Event form only.
                x-enum:
                - response.turn_rollup
                type: string
              query_id:
                description: Event form only.
                type: string
              n_steps:
                description: Reasoning steps the turn ran.
                type: integer
                format: int64
              n_tool_calls:
                description: How many calls the whole turn made.
                type: integer
                format: int64
              by_category:
                description: Tool calls tallied by category.
                type: object
                additionalProperties:
                  description: Calls made in that category.
                  type: integer
                  format: int64
              total_hits:
                description: Retrieved items across all calls, before dedup.
                type: integer
                format: int64
              duration_ms:
                description: Wall time for the whole turn.
                type: integer
                format: int64
              cache_read_tokens:
                description: Input tokens served from the prompt cache.
                type: integer
                format: int64
              cache_write_tokens:
                description: Input tokens written into the prompt cache.
                type: integer
                format: int64
        synthesis:
          nullable: true
          description: The answer completion's cost. Null on a turn that skipped synthesis, as retrieval-only turns do.
          type: object
          allOf:
          - title: Response synthesis
            description: Token counts and latency for the answer completion — the final compose step, not the retrieval loop the steps describe. Served both as the stored `response.synthesis` event and as part of a turn.
            x-component-name: QuerySynthesis
            type: object
            properties:
              type:
                description: Event form only.
                x-enum:
                - response.synthesis
                type: string
              query_id:
                description: Event form only.
                type: string
              status:
                description: How synthesis ended, e.g. `completed`.
                type: string
              tokens_in:
                description: The completion's input tokens.
                type: integer
                format: int64
              tokens_out:
                description: The completion's output tokens.
                type: integer
                format: int64
              ms:
                description: Wall time of the completion.
                type: integer
                format: int64
              answer_preview:
                description: Leading characters of the answer, for a progress display that has no full text yet.
                type: string
              tokens_in_cached:
                description: Input tokens served from the prompt cache.
                type: integer
                format: int64
              tokens_in_cache_write:
                description: Input tokens written into the prompt cache.
                type: integer
                format: int64
              tokens_in_fresh:
                description: Input tokens neither cached nor cache-written.
                type: integer
                format: int64
        trace_ref:
          nullable: true
          description: Blob key of the persisted trace. Fetch the trace itself from `GET /queries/{id}/trace`.
          type: string
        usage:
          description: The turn's token totals. Embed and rerank bill on their own seam and are not counted here.
          type: object
          properties:
            input_tokens:
              description: Input tokens the turn billed.
              type: integer
              format: int64
            output_tokens:
              description: Output tokens the turn billed.
              type: integer
              format: int64
            total_tokens:
              description: Input plus output tokens.
              type: integer
              format: int64
          required:
          - input_tokens
          - output_tokens
          - total_tokens
        runtime_ms:
          description: Wall time from turn start to terminal state.
          type: integer
          format: int64
      required:
      - id
      - object
      - session_id
      - created
      - status
      - input
      - output
      - citations
      - steps
      - usage
      - runtime_ms
    QueryComparisonMember:
      description: One sibling turn of a Compare run — the same ask answered under a different workflow or model.
      type: object
      properties:
        workflow:
          description: The workflow that turn ran.
          type: string
        query_id:
          description: That turn's id. Fetch it with `GET /queries/{id}`.
          type: string
        model:
          description: The model that answered it.
          type: string
    QueryCreatedEvent:
      title: Response created
      description: The turn was accepted. First frame of every stream.
      type: object
      properties:
        type:
          description: Identifies the event.
          x-enum:
          - response.created
          type: string
        query_id:
          description: The turn that was created.
          type: string
        session_id:
          description: The session the turn runs in — the one it continued, or the one it just started.
          type: string
    QueryDefaults:
      description: What `max_steps` and `thinking_level` resolve to when `POST /query` omits them. Read these to populate a picker rather than hard-coding the caps.
      type: object
      properties:
        max_steps:
          description: Workflow selector → its agentic tool-loop step cap. Keyed by the same selectors `POST /query` accepts, since each runs a different loop.
          type: object
          additionalProperties:
            description: The step cap that selector runs with.
            type: integer
            format: int64
        thinking_levels:
          description: Every accepted `thinking_level`, ascending. A value outside this list is rejected with `400`.
          type: array
          items:
            description: One reasoning depth the deployment allows.
            type: string
        thinking_level:
          description: The level a turn runs at when the request omits one.
          type: string
      required:
      - max_steps
      - thinking_levels
      - thinking_level
    QueryEvent:
      title: Progress event
      description: One progress event on a turn, discriminated by `type`. Emitted as SSE frames by a streaming `POST /query` and by `GET /queries/{id}/events`. An event whose `type` this version does not know is dropped rather than ending the turn.
      oneOf:
      - $ref: '#/components/schemas/QueryCreatedEvent'
      - $ref: '#/components/schemas/QueryStepEvent'
      - $ref: '#/components/schemas/QueryOutputTextDeltaEvent'
      - $ref: '#/components/schemas/TurnRollup'
      - $ref: '#/components/schemas/QuerySynthesis'
      - $ref: '#/components/schemas/QueryTraceEvent'
      - $ref: '#/components/schemas/QueryTerminalEvent'
    QueryOutputTextDeltaEvent:
      title: Response output text delta
      description: Answer text. Delivered as one delta once the runtime reports the turn, not token by token.
      type: object
      properties:
        type:
          description: Identifies the event.
          x-enum:
          - response.output_text.delta
          type: string
        query_id:
          description: The turn the text belongs to.
          type: string
        delta:
          description: The answer text.
          type: string
    QueryRequest:
      description: One KnowQL query turn. `scope` and the session-config fields are honored only when starting a NEW session and are pinned for its life; continue an existing one with `session_id` or `previous_query_id`. Every other field rides the turn and is not pinned.
      type: object
      properties:
        ask:
          description: The natural-language question
          type: string
        scope:
          description: Context slugs/UUIDs. New session only; pinned for the session's life. A scope may not mix work and search contexts.
          type: array
          items:
            description: A context slug or UUID.
            type: string
          minItems: 1
          maxItems: 10
        session_id:
          description: Continue an existing session
          type: string
        previous_query_id:
          description: Continue the session this query belongs to
          type: string
        workflow:
          description: Search workflow for this turn. Ignored for work contexts, which always run the `work` runtime.
          x-enum:
          - search
          - search_cc
          - search_rag
          type: string
        system_prompt:
          description: Instructions pinned to a new session
          type: string
        guardrails:
          description: Guardrails pinned to a new session
          type: string
        shape:
          description: JSON Schema subset for structured output; result in output_json
          type: object
          additionalProperties: true
        model:
          description: A catalog model id from `GET /models`, or a tier name (`lite`, `standard`, `pro`) to let the deployment resolve one. New session only; pinned for the session's life.
          type: string
        models:
          description: Ordered fallback list, tried in turn. Takes precedence over `model`.
          type: array
          items:
            description: A catalog model id or tier name.
            type: string
        tools:
          description: Tool names the turn may call. New session only; pinned for the session's life.
          type: array
          items:
            description: A tool name.
            type: string
        stream:
          description: SSE streaming. Mutually exclusive with background.
          type: boolean
        background:
          description: 'Fire-and-forget: 202 + in_progress query; poll GET /queries/{id}. Mutually exclusive with stream.'
          type: boolean
        timeout_seconds:
          description: May only LOWER the 15-minute (900s) cap
          type: integer
          format: int64
        max_steps:
          description: Cap the agent's tool-loop steps for this turn
          type: integer
          format: int64
        thinking_level:
          description: Gemini reasoning depth. Default `low`. Gemini-backed workflows only; ignored for `search_cc`.
          x-enum:
          - minimal
          - low
          - medium
          - high
          type: string
        compose:
          description: Set `false` to skip synthesis, the same as `retrieval_only`.
          type: boolean
        retrieval_only:
          description: Skip synthesis; return retrieved hits in `output_json`
          type: boolean
        pointers_only:
          description: Skip synthesis; return just pointers in `output_json`
          type: boolean
        chunks_only:
          description: Retrieval-only, narrowed to chunks
          type: boolean
        artifacts_only:
          description: Retrieval-only, narrowed to artifacts
          type: boolean
        max_retrieved:
          description: Cap the item count for retrieval-only turns
          type: integer
          format: int64
        max_retrieved_chars:
          description: Cap per-item verbatim text length for retrieval-only turns
          type: integer
          format: int64
        comparison_group:
          description: Client-generated id shared by the turns of one Compare run, so a query cap counts them as one action rather than several. Where the cap applies, a group is limited to 3 turns and a fourth is refused with `409`. Omit for a normal query.
          type: string
      required:
      - ask
    QueryStep:
      description: One step of a turn's reasoning loop. `step_id`, `status`, and `commentary` are always set; the rest are reduced from whatever the step's event carried, so an absent key stays absent.
      type: object
      properties:
        step_id:
          description: Identifies the step within the turn. Clients merge repeated events by it.
          type: string
        status:
          description: How far the step has got.
          x-enum:
          - running
          - completed
          - failed
          type: string
        commentary:
          description: The model's own one-line account of what this step is doing.
          type: string
        fns:
          description: Tool functions this step called.
          type: array
          items:
            description: A tool function name.
            type: string
        strategy:
          $ref: '#/components/schemas/StepStrategy'
        tool_calls:
          description: Per-call detail for the step's tool calls.
          type: array
          items:
            $ref: '#/components/schemas/TraceCall'
        code:
          $ref: '#/components/schemas/StepCode'
        trace_truncated:
          $ref: '#/components/schemas/StepTruncation'
        cost:
          $ref: '#/components/schemas/StepCost'
        input_tokens:
          description: Prompt tokens billed by this one step.
          type: integer
          format: int64
        output_tokens:
          description: Completion tokens billed by this one step.
          type: integer
          format: int64
        total_tokens:
          description: Prompt plus completion for this one step.
          type: integer
          format: int64
        cum_input_tokens:
          description: Turn-to-date input tokens, including this step.
          type: integer
          format: int64
        cum_output_tokens:
          description: Turn-to-date output tokens, including this step.
          type: integer
          format: int64
      required:
      - step_id
      - status
      - commentary
    QueryStepEvent:
      title: Response step
      description: A reasoning step started or finished. The body is the same step shape a finished turn serves in `steps[]`, since those are reduced from these events.
      allOf:
      - description: The event envelope wrapped around the step.
        type: object
        properties:
          type:
            description: Identifies the event.
            x-enum:
            - response.step
            type: string
          query_id:
            description: The turn the step belongs to.
            type: string
      - $ref: '#/components/schemas/QueryStep'
    QueryStream:
      description: 'Each progress frame carries an `id:` (the sequence number — send it back as `Last-Event-ID` to resume), an `event:` name equal to the QueryEvent `type`, and that event as its JSON `data:`. A final `event: query` frame closes the stream with the full Query document and no `id:`.'
      oneOf:
      - $ref: '#/components/schemas/QueryEvent'
      - $ref: '#/components/schemas/Query'
    QuerySynthesis:
      title: Response synthesis
      description: Token counts and latency for the answer completion — the final compose step, not the retrieval loop the steps describe. Served both as the stored `response.synthesis` event and as part of a turn.
      type: object
      properties:
        type:
          description: Event form only.
          x-enum:
          - response.synthesis
          type: string
        query_id:
          description: Event form only.
          type: string
        status:
          description: How synthesis ended, e.g. `completed`.
          type: string
        tokens_in:
          description: The completion's input tokens.
          type: integer
          format: int64
        tokens_out:
          description: The completion's output tokens.
          type: integer
          format: int64
        ms:
          description: Wall time of the completion.
          type: integer
          format: int64
        answer_preview:
          description: Leading characters of the answer, for a progress display that has no full text yet.
          type: string
        tokens_in_cached:
          description: Input tokens served from the prompt cache.
          type: integer
          format: int64
        tokens_in_cache_write:
          description: Input tokens written into the prompt cache.
          type: integer
          format: int64
        tokens_in_fresh:
          description: Input tokens neither cached nor cache-written.
          type: integer
          format: int64
    QueryTerminalEvent:
      title: Response completed / failed / cancelled
      description: How the turn ended. The last progress frame; a final unstamped `query` frame carrying the whole turn follows it.
      type: object
      properties:
        type:
          description: Identifies the event, and which terminal state was reached.
          x-enum:
          - response.completed
          - response.failed
          - response.cancelled
          type: string
        query_id:
          description: The turn that ended.
          type: string
        error:
          description: Failure detail. Set on the failed and cancelled events only.
          type: string
    QueryTraceEvent:
      title: Response trace
      description: The turn's trace blob has landed.
      type: object
      properties:
        type:
          description: Identifies the event.
          x-enum:
          - response.trace
          type: string
        query_id:
          description: The turn the trace belongs to.
          type: string
        trace_ref:
          description: Blob key of the persisted trace.
          type: string
    RestoreCompletedOutput:
      title: Restore completed
      description: The target holds the pack's sources, knowledge, and manifest. Its index stays empty until curated.
      type: object
      properties:
        state:
          description: Which stage of the restore this report describes.
          type: string
        pack_filename:
          description: The pack archive's file name.
          type: string
        pack_size:
          description: How large the archive is on disk.
          type: integer
          format: int64
        target_context_id:
          description: The context the pack is restored into.
          type: string
        target_slug:
          description: URL-safe name of the context being written into.
          type: string
        sources_staged:
          description: Source files written into the target.
          type: integer
          format: int64
        knowledge_staged:
          description: Knowledge files written into the target.
          type: integer
          format: int64
        manifest_set:
          description: Whether the pack's manifest was pinned onto the target.
          type: boolean
        corpus_groups_set:
          description: Corpus groups written into the target's curation ledger.
          type: integer
          format: int64
        sample_queries:
          description: Sample queries carried from the pack onto the target. Empty when the pack had none.
          type: array
          items:
            description: One sample query set on the target.
            type: string
        started_at:
          description: When the restore started.
          type: string
        completed_at:
          description: When the restore finished.
          type: string
      required:
      - state
      - pack_filename
      - pack_size
      - target_context_id
      - target_slug
      - sources_staged
      - knowledge_staged
      - manifest_set
      - corpus_groups_set
      - sample_queries
      - started_at
      - completed_at
    RestoreInput:
      title: Restore
      description: What a restore run was started with.
      type: object
      properties:
        pack_key:
          description: Object-store key of the pack being restored.
          type: string
        pack_filename:
          description: The pack archive's file name.
          type: string
        target_context_id:
          description: The already-created context the pack is restored into.
          type: string
        target_slug:
          description: URL-safe name of the context being written into.
          type: string
        target_name:
          description: Human-readable label of the context being written into.
          type: string
        sample_queries:
          description: Sample queries to seed the target with, taken from the pack. Absent on a pack that carried none.
          type: array
          items:
            description: One sample query carried over from the pack.
            type: string
      required:
      - pack_key
      - pack_filename
      - target_context_id
      - target_slug
      - target_name
    RestoreRunningOutput:
      title: Restore running
      description: 'A restore''s progress: the initial claim, the fetch, the unzip, then periodic staging. `state` is `running` on all four, so key presence is what tells them apart, and only `state` is on every one.'
      type: object
      properties:
        state:
          description: Always `running`. Which report this is shows in the keys it carries, not here.
          x-enum:
          - running
          type: string
        pack_filename:
          description: The pack archive's file name. Absent on the staging report.
          type: string
        pack_size:
          description: Byte size of the pack archive. Present once it has been fetched.
          type: integer
          format: int64
        target_context_id:
          description: The context the pack is restored into. Absent on the staging report.
          type: string
        target_slug:
          description: Slug of that target context. Absent from the unzip and staging reports.
          type: string
        started_at:
          description: When the restore started. Present on the first report only.
          type: string
        stage_progress:
          description: How far the current phase has got. Absent on the first report, before any phase begins.
          allOf:
          - $ref: '#/components/schemas/StageProgress'
        sources_count:
          description: Source files found in the pack. Present once it has been expanded.
          type: integer
          format: int64
        knowledge_count:
          description: Knowledge files found in the pack. Present once it has been expanded.
          type: integer
          format: int64
      required:
      - state
    SeamUsage:
      description: 'Per-model embed/rerank-seam counts: billed per token (embed) or per request (rerank).'
      type: object
      properties:
        kind:
          description: Which seam this row counts, and therefore which of the two count fields is meaningful.
          x-enum:
          - embed
          - rerank
          type: string
        tier:
          description: Which tier resolved to this model.
          type: string
        embed_tokens:
          description: 'Tokens embedded. Meaningful for `kind: embed`.'
          type: integer
          format: int64
        rerank_units:
          description: 'Rerank requests made. Meaningful for `kind: rerank`.'
          type: integer
          format: int64
      required:
      - kind
      - tier
      - embed_tokens
      - rerank_units
    SearchCcTurnCompletedOutput:
      title: Search-as-code completed
      description: The search-as-code path reports a step count where the others report `output_json`.
      type: object
      properties:
        status:
          description: How the turn ended.
          type: string
        query_id:
          description: The turn this task answered.
          type: string
        answer:
          description: The answer text.
          type: string
        citations:
          description: Cited source paths.
          type: array
          items:
            description: A cited source path.
            type: string
        latency_ms:
          description: Wall time for the turn.
          type: integer
          format: int64
        steps:
          description: Reasoning steps the turn ran.
          type: integer
          format: int64
      required:
      - status
      - query_id
      - answer
      - citations
      - latency_ms
      - steps
    SearchInput:
      title: Search / search_cc / search_rag / work
      description: One shape for the whole search family — the same payload is written whichever of them a turn resolves to.
      type: object
      properties:
        session_id:
          description: The session the turn runs in.
          type: string
        query_id:
          description: The turn this task serves.
          type: string
        ask:
          description: Title fallback for the tasks UI; empty when the turn had no user message
          type: string
        messages:
          description: The conversation history handed to the runtime.
          type: array
          items:
            description: One message of history.
            type: object
            properties:
              role:
                description: Who sent it, e.g. `user`.
                type: string
              content:
                description: The message text.
                type: string
            required:
            - role
            - content
        models:
          description: The session's model fallback list, in preference order.
          type: array
          items:
            description: A catalog model id or tier name.
            type: string
        tools:
          description: Tool names the turn may call.
          type: array
          items:
            description: A tool name.
            type: string
        shape:
          nullable: true
          description: JSON Schema the answer must conform to. Null on a free-text turn.
          type: object
          additionalProperties: true
        instructions:
          nullable: true
          description: The session's system prompt. Null when none was pinned.
          type: string
        scope:
          description: Context ids the turn searches.
          type: array
          items:
            description: A context id the turn searched.
            type: string
        turn_timeout_seconds:
          description: Runtime budget for this one turn.
          type: integer
          format: int64
        retrieval:
          description: The turn's retrieval controls.
          type: object
          properties:
            retrieval_only:
              nullable: true
              description: Skip synthesis and return the hits. Null where the caller omitted it.
              type: boolean
            pointers_only:
              nullable: true
              description: Skip synthesis and return pointers only. Null where the caller omitted it.
              type: boolean
            chunks_only:
              nullable: true
              description: Narrow retrieval to chunks. Null where the caller omitted it.
              type: boolean
            artifacts_only:
              nullable: true
              description: Narrow retrieval to artifacts. Null where the caller omitted it.
              type: boolean
            max_retrieved:
              nullable: true
              description: Cap on retrieved items. Null where the caller omitted it.
              type: integer
              format: int64
            max_retrieved_chars:
              nullable: true
              description: Cap on per-item text length. Null where the caller omitted it.
              type: integer
              format: int64
            compose:
              nullable: true
              description: Whether to synthesize an answer. Null where the caller omitted it.
              type: boolean
            max_steps:
              nullable: true
              description: Cap on the agent's tool-loop steps. Null where the caller omitted it.
              type: integer
              format: int64
            thinking_level:
              nullable: true
              description: Reasoning depth. Null where the caller omitted it.
              x-enum:
              - minimal
              - low
              - medium
              - high
              type: string
          required:
          - retrieval_only
          - pointers_only
          - chunks_only
          - artifacts_only
          - max_retrieved
          - max_retrieved_chars
          - compose
          - max_steps
          - thinking_level
        comparison_group:
          nullable: true
          description: The Compare run this turn belongs to. Null on a normal single query.
          type: string
      required:
      - session_id
      - query_id
      - ask
      - messages
      - models
      - tools
      - shape
      - instructions
      - scope
      - turn_timeout_seconds
      - comparison_group
    SearchManifest:
      description: Standing instructions for the query runtime, pinned on the context rather than sent per turn.
      type: object
      properties:
        instructions:
          description: The context's default system prompt, applied to every turn in scope. A session's own `system_prompt` appends to it rather than replacing it.
          type: string
    SearchTurnCompletedOutput:
      title: Search / search_rag completed
      description: What a finished search turn's task reports. The turn itself, with its steps and structured citations, is at `GET /queries/{query_id}`.
      type: object
      properties:
        status:
          description: How the turn ended.
          type: string
        query_id:
          description: The turn this task answered.
          type: string
        answer:
          description: The answer text.
          type: string
        output_json:
          nullable: true
          description: Structured answer when the turn carried a shape, or the hits on a retrieval-only turn. Absent otherwise.
          type: object
          additionalProperties: true
        citations:
          description: Cited source paths. The turn carries the structured form.
          type: array
          items:
            description: A cited source path.
            type: string
        latency_ms:
          description: Wall time for the turn.
          type: integer
          format: int64
        unknown_models:
          description: Model selections dropped as unknown before dispatch, so a caller whose pin was silently ignored can see it. Absent when nothing was dropped.
          type: array
          items:
            description: A requested model id or tier name the project's catalog does not carry.
            type: string
      required:
      - status
      - query_id
      - answer
      - citations
      - latency_ms
    SearchTurnFailedOutput:
      title: Search failed
      description: What a search turn reports when it could not answer.
      type: object
      properties:
        status:
          description: How the turn ended.
          type: string
        query_id:
          description: The turn that failed.
          type: string
        error:
          description: Why the turn failed.
          type: string
      required:
      - status
      - query_id
      - error
    Session:
      description: A project-owned conversation thread of queries. Its scope and configuration are pinned when the first turn creates it and cannot be changed afterwards.
      type: object
      properties:
        id:
          description: Session id, `ses_<uuid>`.
          type: string
        project_id:
          description: The Pinecone project that owns the session.
          type: string
        workspace:
          description: Owning workspace. Absent off a workspace-enabled cluster.
          type: string
        created_by:
          description: Principal whose first turn created the session.
          type: string
        scope:
          description: Pinned context UUIDs (1–10) every turn searches.
          type: array
          items:
            description: A pinned context UUID.
            type: string
        title:
          nullable: true
          description: Display title derived from the opening ask. Null until one is written.
          type: string
        system_prompt:
          nullable: true
          description: Instructions pinned at session creation. Null when none were given.
          type: string
        guardrails:
          nullable: true
          description: Guardrails pinned at session creation. Null when none were given.
          type: string
        models:
          description: Pinned model fallback list, in preference order.
          type: array
          items:
            description: A catalog model id or tier name.
            type: string
        tools:
          description: Tool names the session's turns may call.
          type: array
          items:
            description: A tool name.
            type: string
        workflow:
          nullable: true
          description: The workflow this session's turns run
          type: string
        last_query_id:
          nullable: true
          description: The most recent turn. Null on a session with no turns yet.
          type: string
        created_at:
          description: When the session was created.
          type: string
          format: date-time
        updated_at:
          description: When the session last changed.
          type: string
          format: date-time
      required:
      - id
      - project_id
      - created_by
      - scope
      - models
      - tools
      - created_at
      - updated_at
    SessionList:
      description: The sessions, newest first.
      type: object
      properties:
        sessions:
          description: The conversation threads.
          type: array
          items:
            $ref: '#/components/schemas/Session'
        queries_active:
          description: Query turns in flight project-wide at the time of the read. Present only when the request asked for it with `queries_active=true`.
          type: integer
          format: int64
      required:
      - sessions
    SessionWithQueries:
      description: The session, with its turns.
      allOf:
      - $ref: '#/components/schemas/Session'
      - description: The turns added on top of the session row.
        type: object
        properties:
          queries:
            description: The session's turns, oldest first.
            type: array
            items:
              $ref: '#/components/schemas/Query'
        required:
        - queries
    SourceFileManifest:
      description: Every source object with its size and modification time.
      type: object
      properties:
        files:
          description: The source objects.
          type: array
          items:
            description: One source object.
            type: object
            properties:
              path:
                description: Path relative to the source-tree root.
                type: string
              size:
                description: Byte size of the stored object.
                type: integer
                format: int64
              last_modified:
                nullable: true
                description: Null when the store reports no modification time.
                type: string
                format: date-time
            required:
            - path
            - size
            - last_modified
        total:
          description: Number of entries in `files`.
          type: integer
          format: int64
      required:
      - files
      - total
    SourceManifestEntry:
      description: What curate recorded about one source. The hash is what makes an incremental curate possible — a source whose hash is unchanged is skipped.
      type: object
      properties:
        hash:
          description: Content hash of the source as curated.
          type: string
        curated_at:
          description: When this source was last curated.
          type: string
          format: date-time
        size:
          description: Byte size at curate time.
          type: integer
          format: int64
        mtime:
          nullable: true
          description: Source modification time at curate time. Null when the store reported none.
          type: string
          format: date-time
      required:
      - hash
      - curated_at
      - size
    SourceRemoved:
      description: A deferred whole-source delete tombstone. The source's index entries are dropped on the next curate rather than at delete time.
      type: object
      properties:
        removed_version:
          description: Index version the delete was recorded against.
          type: integer
          format: int64
        removed_at:
          nullable: true
          description: When the delete was requested.
          type: string
          format: date-time
      required:
      - removed_version
    SourceStats:
      description: Source-tree counts, plus the caps and the usage against them where source limits apply.
      allOf:
      - $ref: '#/components/schemas/FileStats'
      - description: The five quota fields travel together and are all absent — never null — where source limits are disabled and no cap applies.
        type: object
        properties:
          max_files_per_context:
            description: Upper bound on how many source objects may be staged.
            type: integer
            format: int64
          max_bytes_per_context:
            description: Total-byte cap for this context.
            type: integer
            format: int64
          max_bytes_per_file:
            description: Upper bound on one stored object.
            type: integer
            format: int64
          used_files:
            description: Files counted against `max_files_per_context`.
            type: integer
            format: int64
          used_bytes:
            description: Bytes counted against `max_bytes_per_context`.
            type: integer
            format: int64
    StageProgress:
      description: How far one restore phase has got.
      type: object
      properties:
        phase:
          description: Which phase is running, e.g. `stage_sources`.
          type: string
        done:
          description: Items finished in this phase.
          type: integer
          format: int64
        total:
          description: Items this phase will process.
          type: integer
          format: int64
      required:
      - phase
      - done
      - total
    StateFailedOutput:
      title: State-keyed failure
      description: The pack / restore terminal-failure convention.
      type: object
      properties:
        state:
          description: How the run ended.
          type: string
        error:
          description: What went wrong.
          type: string
      required:
      - state
      - error
    StatusErrorOutput:
      title: Status-keyed failure
      description: 'What a groom or curate reports when it fails terminally: best-effort detail on a task left running so it can be resumed.'
      type: object
      properties:
        status:
          description: How the run ended.
          type: string
        error:
          description: What went wrong.
          type: string
      required:
      - status
      - error
    StepCode:
      description: A step's generated code, capped. Either the source string alone or a `{language, source}` document.
      oneOf:
      - title: Source
        description: The source string alone, as later rows store it.
        type: string
      - title: Document
        description: The language-tagged form earlier rows store.
        type: object
        properties:
          language:
            description: Language the code is written in.
            type: string
          source:
            description: The code itself.
            type: string
    StepCost:
      description: The step's incremental token and latency cost — deltas against the running turn cursor, not totals. The cache fields are tracked only on the search-as-code path.
      type: object
      properties:
        tokens_in:
          description: The step's input tokens.
          type: integer
          format: int64
        tokens_out:
          description: The step's output tokens.
          type: integer
          format: int64
        decide_ms:
          description: Time spent choosing what to do.
          type: integer
          format: int64
        execute_ms:
          description: Time spent running the tool calls it chose.
          type: integer
          format: int64
        tokens_in_cached:
          description: Input tokens served from the prompt cache.
          type: integer
          format: int64
        tokens_in_cache_write:
          description: Input tokens written into the prompt cache.
          type: integer
          format: int64
        tokens_in_fresh:
          description: Input tokens neither cached nor cache-written.
          type: integer
          format: int64
    StepStrategy:
      description: The retrieval approach the step picked.
      type: object
      properties:
        kind:
          description: Strategy family, e.g. `artifacts_first`.
          type: string
        fns:
          description: Tool functions the strategy calls.
          type: array
          items:
            description: A tool function name.
            type: string
        label:
          description: Display label for the strategy.
          type: string
        scope:
          description: Context ids the strategy searched.
          type: array
          items:
            description: A context id the strategy searched.
            type: string
    StepTruncation:
      description: What a clamp shed from an oversized step event.
      type: object
      properties:
        truncated:
          description: Whether the clamp fired at all.
          type: boolean
        dropped_documents:
          description: Retrieved documents shed from the event.
          type: integer
          format: int64
        dropped_tool_calls:
          description: How many calls the clamp discarded.
          type: integer
          format: int64
    TaskFileListing:
      description: A task's file listing. Which branch answers depends on whether the task's files are still live or already archived.
      oneOf:
      - $ref: '#/components/schemas/ArchivedFileListing'
      - $ref: '#/components/schemas/LiveFileListing'
    TaskFileMetadata:
      description: A stat on one task file — the archived or the live shape, depending on whether the task still has a container.
      oneOf:
      - title: Archived
        description: Read after the task's files were archived.
        type: object
        properties:
          is_dir:
            description: Whether the object is a directory.
            type: boolean
          is_file:
            description: Whether the object is a regular file.
            type: boolean
          size:
            description: Byte size.
            type: integer
            format: int64
          modified:
            nullable: true
            description: Unix seconds. Null when the store reports none.
            type: integer
            format: int64
        required:
        - is_dir
        - is_file
        - size
        - modified
      - title: Live
        description: A `stat` in the running container.
        type: object
        properties:
          kind:
            description: 'Entry kind: `file`, `dir` or `symlink` when the stat is recognized, and the raw stat word otherwise.'
            type: string
          size:
            description: Byte size.
            type: integer
            format: int64
          mode:
            description: POSIX permission bits, as reported by the container.
            type: string
          mtime:
            description: Last-modified time as the container reported it.
            type: string
          link_target:
            description: Where the link points. Present only for a symlink.
            type: string
        required:
        - kind
        - size
        - mode
        - mtime
    TaskInput:
      description: A task's per-workflow `input`. It carries no discriminant of its own — the sibling `workflow` field selects the shape.
      anyOf:
      - $ref: '#/components/schemas/SearchInput'
      - $ref: '#/components/schemas/CurateInput'
      - $ref: '#/components/schemas/ImportInput'
      - $ref: '#/components/schemas/PackInput'
      - $ref: '#/components/schemas/RestoreInput'
      - $ref: '#/components/schemas/ExploreInput'
      - $ref: '#/components/schemas/ProfileInput'
      - $ref: '#/components/schemas/OptimizeInput'
      - $ref: '#/components/schemas/GroomInput'
    TaskList:
      description: One page of task records.
      type: object
      properties:
        items:
          description: The tasks on this page.
          type: array
          items:
            $ref: '#/components/schemas/TaskResponse'
        total:
          description: Tasks matching the filter, across every page.
          type: integer
          format: int64
        limit:
          description: Maximum tasks per page.
          type: integer
          format: int64
        offset:
          description: Where this page starts.
          type: integer
          format: int64
        page:
          description: 1-based index of this page.
          type: integer
          format: int64
        pages:
          description: Total pages available.
          type: integer
          format: int64
      required:
      - items
      - total
      - limit
      - offset
      - page
      - pages
    TaskOutput:
      nullable: true
      description: A task's reported `output`. Every workflow reports a different per-state shape, matched to a named variant only when its key set is exactly that variant's; anything else is preserved as stored. Treat this union as open. Null until the run reports anything.
      anyOf:
      - $ref: '#/components/schemas/SearchTurnCompletedOutput'
      - $ref: '#/components/schemas/SearchCcTurnCompletedOutput'
      - $ref: '#/components/schemas/SearchTurnFailedOutput'
      - $ref: '#/components/schemas/PackRunningOutput'
      - $ref: '#/components/schemas/PackCompletedOutput'
      - $ref: '#/components/schemas/RestoreRunningOutput'
      - $ref: '#/components/schemas/RestoreCompletedOutput'
      - $ref: '#/components/schemas/OptimizeResultOutput'
      - $ref: '#/components/schemas/OptimizeNoopOutput'
      - $ref: '#/components/schemas/GroomMetricsOutput'
      - $ref: '#/components/schemas/CurateRunOutput'
      - $ref: '#/components/schemas/CurateManifestTuneOutput'
      - $ref: '#/components/schemas/CurateNoopOutput'
      - $ref: '#/components/schemas/ExploreOutput'
      - $ref: '#/components/schemas/ProfileEstimateOutput'
      - $ref: '#/components/schemas/ProfileEmptyOutput'
      - $ref: '#/components/schemas/ImportOutput'
      - $ref: '#/components/schemas/StatusErrorOutput'
      - $ref: '#/components/schemas/StateFailedOutput'
      - $ref: '#/components/schemas/ErrorOutput'
      - title: Other
        description: Any shape without a named variant
        type: object
        additionalProperties: true
    TaskProgress:
      description: Coarse run progress, written by the runtime. Absent on a task that reports none.
      type: object
      properties:
        phase:
          description: 1-based index of the phase now running.
          type: integer
          format: int64
        phases:
          description: Total phases this run expects.
          type: integer
          format: int64
        label:
          description: What the current phase is doing.
          type: string
        pct:
          description: Completion across the whole run, 0–100.
          type: number
          format: double
        eta_seconds:
          nullable: true
          description: Estimated seconds remaining. Null when the run cannot estimate one.
          type: integer
          format: int64
      required:
      - phase
      - phases
      - label
      - pct
    TaskResponse:
      description: One task record — a single run of a workflow, owned by the project.
      type: object
      properties:
        id:
          description: Task id.
          type: string
        project_id:
          description: The Pinecone project that owns the task.
          type: string
        context_id:
          nullable: true
          description: The context the run acts on. Null for a task that belongs to no context.
          type: string
        agent_id:
          nullable: true
          description: Reserved. Null on every task this version serves.
          type: string
        session_id:
          nullable: true
          description: Set for query turns
          type: string
        created_by:
          description: Principal that started the run.
          type: string
        workflow:
          $ref: '#/components/schemas/Workflow'
        state:
          $ref: '#/components/schemas/TaskState'
        error:
          nullable: true
          description: Failure detail. Set on a `failed` task.
          type: string
        input:
          $ref: '#/components/schemas/TaskInput'
        output:
          $ref: '#/components/schemas/TaskOutput'
        steps:
          description: Populated only on GET /tasks/{id}. May be a trailing window when `steps_limit` was given, so read the count from `steps_total` rather than this array's length.
          type: array
          items:
            $ref: '#/components/schemas/TaskStep'
        steps_total:
          description: True number of recorded steps. Absent on a read that carries no steps.
          type: integer
          format: int64
        tokens_prompt:
          description: Input tokens the run has billed so far.
          type: integer
          format: int64
        tokens_completion:
          description: Output tokens the run has billed so far.
          type: integer
          format: int64
        runtime_seconds:
          description: Seconds the container has been running.
          type: integer
          format: int64
        running_from:
          nullable: true
          description: When the container started. Null before it does.
          type: string
          format: date-time
        timeout_seconds:
          nullable: true
          description: Runtime budget for this task. Null when it runs uncapped.
          type: integer
        timeout_at:
          nullable: true
          description: When the budget expires and the run is terminated.
          type: string
          format: date-time
        archived_at:
          nullable: true
          description: When the task's files were archived. Null while they are still live.
          type: string
          format: date-time
        created_at:
          description: When the task row was created.
          type: string
          format: date-time
        last_activity_at:
          nullable: true
          description: When the runtime last reported anything. Drives stall detection.
          type: string
          format: date-time
        schedule:
          nullable: true
          description: Cron expression this run was scheduled from. Null for an on-demand run.
          type: string
        scheduled_at:
          nullable: true
          description: When a `scheduled` task is due to start.
          type: string
          format: date-time
        parent_task_id:
          nullable: true
          description: The task that spawned this one, as an optimize spawns its curates.
          type: string
        progress:
          $ref: '#/components/schemas/TaskProgress'
      required:
      - id
      - project_id
      - created_by
      - workflow
      - state
      - input
      - steps
      - tokens_prompt
      - tokens_completion
      - runtime_seconds
      - created_at
    TaskState:
      description: Where the run has got to. `scheduled` waits for its due time; `starting` and `provisioning` are a container being claimed and built; `running` is the work happening; `stopping` is a termination in progress. `completed`, `cancelled` and `failed` are terminal.
      x-enum:
      - scheduled
      - starting
      - provisioning
      - running
      - stopping
      - completed
      - cancelled
      - failed
      type: string
    TaskStep:
      description: One reported step row. `step_id` and `status` are always set; the rest are per-workflow optionals, so an absent key stays absent.
      type: object
      properties:
        step_id:
          description: Identifies the step within the task.
          type: string
        status:
          description: How the step ended, e.g. `running` or `completed`.
          type: string
        type:
          description: What kind of step this is; the vocabulary is per-workflow.
          type: string
        content:
          description: The step's reported text payload.
          type: string
        commentary:
          description: The runtime's one-line account of what the step is doing.
          type: string
        code:
          description: Redacted tool input (search)
          type: string
        result:
          description: Redacted tool output (search)
          type: string
        cum_input_tokens:
          description: Task-to-date input tokens, including this step.
          type: integer
          format: int64
        cum_output_tokens:
          description: Task-to-date output tokens, including this step.
          type: integer
          format: int64
        job_id:
          description: Identifier of the LlamaParse job doing the work.
          type: string
        path:
          description: Source path being parsed
          type: string
      required:
      - step_id
      - status
    TemplateMatch:
      description: One manifest template an explore run proposes for the corpus.
      type: object
      properties:
        template_id:
          description: Catalog entry the run proposes for this corpus.
          type: string
        rationale:
          description: Why the run thinks this template fits the corpus.
          type: string
        confidence:
          description: How sure the run is, 0–1. Low-confidence proposals are dropped before this point.
          type: number
          format: double
      required:
      - template_id
      - rationale
      - confidence
    Trace:
      description: A turn's full-fidelity debug trace. Every turn lands one.
      type: object
      properties:
        steps:
          description: The turn's reasoning steps, in the order they ran.
          type: array
          items:
            $ref: '#/components/schemas/TraceStep'
        rollup:
          nullable: true
          description: Null on a turn the runtime never closed. The trace's copy omits the `type` and `query_id` the event form carries.
          type: object
          allOf:
          - title: Response turn rollup
            description: A turn's end-of-turn counters. Served both as the stored `response.turn_rollup` event, which adds `type` and `query_id`, and as the trace blob's copy, which does not.
            x-component-name: TurnRollup
            type: object
            properties:
              type:
                description: Event form only.
                x-enum:
                - response.turn_rollup
                type: string
              query_id:
                description: Event form only.
                type: string
              n_steps:
                description: Reasoning steps the turn ran.
                type: integer
                format: int64
              n_tool_calls:
                description: How many calls the whole turn made.
                type: integer
                format: int64
              by_category:
                description: Tool calls tallied by category.
                type: object
                additionalProperties:
                  description: Calls made in that category.
                  type: integer
                  format: int64
              total_hits:
                description: Retrieved items across all calls, before dedup.
                type: integer
                format: int64
              duration_ms:
                description: Wall time for the whole turn.
                type: integer
                format: int64
              cache_read_tokens:
                description: Input tokens served from the prompt cache.
                type: integer
                format: int64
              cache_write_tokens:
                description: Input tokens written into the prompt cache.
                type: integer
                format: int64
    TraceCall:
      description: One tool call within a step.
      type: object
      properties:
        fn:
          description: Name of the function this call invoked.
          type: string
        category:
          description: Which family the tool belongs to, as tallied in the rollup's `by_category`.
          type: string
        args:
          description: Compact, redacted summary of the call's arguments. The key set is tool-specific and deliberately open.
          type: object
          additionalProperties: true
        result:
          description: Compact summary of the call's result (never the payload). The shape varies by category and is runtime-extensible.
        duration_ms:
          description: Wall time for this one call.
          type: integer
          format: int64
        ok:
          description: Whether the call succeeded.
          type: boolean
        score_space:
          description: Which scoring space the returned scores live in, for calls that retrieve.
          type: string
        error:
          description: Failure detail. Set when `ok` is false.
          type: string
    TraceStep:
      description: One reasoning step as recorded in the trace — its generated code, tool calls, strategy, and cost. Every field is optional; a step carries what its stage produced.
      type: object
      properties:
        step_id:
          description: Identifies the step within the turn.
          type: string
        commentary:
          description: The model's own one-line account of what this step is doing.
          type: string
        code:
          $ref: '#/components/schemas/StepCode'
        calls:
          description: The tool calls this step made.
          type: array
          items:
            $ref: '#/components/schemas/TraceCall'
        strategy:
          $ref: '#/components/schemas/StepStrategy'
        cost:
          $ref: '#/components/schemas/StepCost'
    TurnRollup:
      title: Response turn rollup
      description: A turn's end-of-turn counters. Served both as the stored `response.turn_rollup` event, which adds `type` and `query_id`, and as the trace blob's copy, which does not.
      type: object
      properties:
        type:
          description: Event form only.
          x-enum:
          - response.turn_rollup
          type: string
        query_id:
          description: Event form only.
          type: string
        n_steps:
          description: Reasoning steps the turn ran.
          type: integer
          format: int64
        n_tool_calls:
          description: How many calls the whole turn made.
          type: integer
          format: int64
        by_category:
          description: Tool calls tallied by category.
          type: object
          additionalProperties:
            description: Calls made in that category.
            type: integer
            format: int64
        total_hits:
          description: Retrieved items across all calls, before dedup.
          type: integer
          format: int64
        duration_ms:
          description: Wall time for the whole turn.
          type: integer
          format: int64
        cache_read_tokens:
          description: Input tokens served from the prompt cache.
          type: integer
          format: int64
        cache_write_tokens:
          description: Input tokens written into the prompt cache.
          type: integer
          format: int64
    UpdateContextConnectorRequest:
      description: The new enabled state.
      type: object
      properties:
        enabled:
          description: Whether this context may import from the connector.
          type: boolean
      required:
      - enabled
    UpdateContextRequest:
      description: All fields optional. Empty string for description/guide clears it; `{}` for manifest clears it back to defaults. Absent leaves untouched. `kind` is immutable and cannot be updated.
      type: object
      properties:
        slug:
          description: Renames the context. Must stay unique within the project.
          type: string
        name:
          description: New display name.
          type: string
        description:
          description: New summary. Empty string clears it.
          type: string
        guide:
          description: New standing instructions. Empty string clears them.
          type: string
        manifest:
          $ref: '#/components/schemas/Manifest'
    UploadContextSourceRequest:
      description: The file to stage. One per request.
      type: object
      properties:
        file:
          description: File bytes. Archives are expanded by the import runtime.
          type: string
          format: binary
      required:
      - file
    Workflow:
      description: The canonical workflow name.
      x-enum:
      - optimize
      - curate
      - search
      - search_cc
      - search_rag
      - work
      - explore
      - profile
      - import
      - pack
      - restore
      - groom
      type: string
    WorkflowTriggerResponse:
      description: 'What every context-workflow trigger returns. The work is asynchronous: poll `GET /tasks/{task_id}`. The per-workflow booleans duplicate `state` and appear only where a workflow''s contract names one.'
      type: object
      properties:
        task_id:
          description: The enqueued task. Poll it at `GET /tasks/{id}`.
          type: string
        state:
          description: The forward-looking status the trigger put the context into.
          x-enum:
          - optimizing
          - grooming
          - exploring
          - profiling
          - importing
          type: string
        exploring:
          description: Duplicates `state`; present only for explore
          type: boolean
        profiling:
          description: Duplicates `state`; present only for profile
          type: boolean
        importing:
          description: Duplicates `state`; present only for the import/curate triggers
          type: boolean
      required:
      - task_id
      - state
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Session token from `POST /auth/login`, sent as `Authorization: Bearer <token>`.'
    apiKey:
      type: apiKey
      in: header
      name: Api-Key
      description: Pinecone API key, accepted as an alternative to the bearer token.
security:
- bearerAuth: []
- apiKey: []
tags:
- name: Auth
  description: Login and identity.
- name: Project
  description: The active Pinecone project and its disclosure state.
- name: Contexts
  description: A context is sources + a manifest. Curate it explicitly before querying.
- name: Manifest
  description: Manifest templates and the per-context manifest.
- name: Source Files
  description: Per-context source imports (upload, connector, public repo) and the source file tree.
- name: Knowledge
  description: Read-only browse of curated knowledge (chunks + artifacts).
- name: Curation
  description: Curate workflow trigger, curation ledger, and version-pin primitives.
- name: Connectors
  description: Project-level links to external source providers (Box, ...). Linked via OAuth or an API key, then used to import source documents into a context.
- name: Query
  description: 'The unified KnowQL Query API: run a query turn (`/query`), fetch a turn (`/queries/{id}`), inspect its trace, manage feedback, comparison flags, and multi-turn sessions (`/sessions`).'
- name: Tasks
  description: Top-level, project-owned task records for every workflow (optimize, curate, search, work, explore, profile, import, pack, restore, groom).
- name: Task Files
  description: Read, list, and delete files from live or archived task containers.