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

# Query artifact metadata

> Executes one bounded, read-only ArtifactQuery statement over indexed artifact metadata for repository-level analytics: language and file-type mix, lines, cognitive complexity, largest files, public API surface, relationship counts. Statements must end with LIMIT. Invalid statements are not executed and return repairable diagnostics — fix the statement per the hint (see `get_artifact_query_schema`) and retry.



## OpenAPI

````yaml /openapi-tool-api-v3.json post /api/tools/query_artifact_metadata
openapi: 3.1.1
info:
  title: CodeAlive Tool API
  description: >-
    Tool-only OpenAPI 3.1 contract for MCP and agent integrations. Every
    operation is read-only and returns a Tool API envelope.
  contact:
    name: CodeAlive Team
    url: https://codealive.ai
    email: support@codealive.ai
  license:
    name: Terms of Service
    url: https://app.codealive.ai/terms
  version: 3.0.0
servers:
  - url: https://app.codealive.ai
security:
  - ApiKeyScheme: []
tags:
  - name: ToolApi
    description: CodeAlive Tool API v3
paths:
  /api/tools/query_artifact_metadata:
    post:
      tags:
        - ToolApi
      summary: Query artifact metadata
      description: >-
        Executes one bounded, read-only ArtifactQuery statement over indexed
        artifact metadata for repository-level analytics: language and file-type
        mix, lines, cognitive complexity, largest files, public API surface,
        relationship counts. Statements must end with LIMIT. Invalid statements
        are not executed and return repairable diagnostics — fix the statement
        per the hint (see `get_artifact_query_schema`) and retry.
      operationId: ToolApiQueryArtifactMetadata
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArtifactMetadataQueryToolRequest'
            example:
              statement: SELECT path, language FROM files LIMIT 20
              data_sources:
                - CodeAlive-AI/agent-framework
          text/json:
            schema:
              $ref: '#/components/schemas/ArtifactMetadataQueryToolRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ArtifactMetadataQueryToolRequest'
      responses:
        '200':
          description: >-
            Success envelope. obj is the execution result: rawStatement,
            resultShape, columns, rows[] (column-keyed dictionaries),
            returnedRows, truncated, limit, dataSourceIds; rendered is the
            JSON-serialized form of obj. Repairable failures (missing or invalid
            arguments, ambiguous or unknown data sources) also return HTTP 200
            with obj.error = { code, message, retry, try } and a rendered
            <tool_error> block; repair the arguments and retry.
          content:
            application/json:
              schema:
                oneOf:
                  - required:
                      - obj
                      - rendered
                    type: object
                    properties:
                      obj:
                        $ref: '#/components/schemas/ArtifactQueryExecutionResultDto'
                      rendered:
                        type: string
                        description: Agent-facing result text.
                    additionalProperties: false
                    description: >-
                      Default success projection returned when output_format is
                      omitted.
                  - required:
                      - obj
                    type: object
                    properties:
                      obj:
                        $ref: '#/components/schemas/ArtifactQueryExecutionResultDto'
                    additionalProperties: false
                    description: >-
                      Structured success projection returned when output_format
                      is json.
                  - required:
                      - rendered
                    type: object
                    properties:
                      rendered:
                        type: string
                        description: Agent-facing result text.
                    additionalProperties: false
                    description: >-
                      Agent-facing success projection returned when
                      output_format is agentic.
                  - required:
                      - obj
                      - rendered
                    type: object
                    properties:
                      obj:
                        $ref: '#/components/schemas/ToolApiRepairableResult'
                      rendered:
                        type: string
                        description: Agent-facing result text.
                    additionalProperties: false
                    description: >-
                      Repairable failure. Always includes both projections and
                      uses HTTP 200.
              examples:
                default:
                  summary: Default success response
                  description: >-
                    Returned when output_format is omitted; includes both
                    projections.
                  value:
                    obj:
                      rawStatement: >-
                        SELECT count() AS count, language FROM files GROUP BY
                        language LIMIT 20
                      version: V1
                      resultShape: GroupedAggregate
                      columns:
                        - count
                        - language
                      rows:
                        - count: 214
                          language: python
                        - count: 32
                          language: markdown
                      returnedRows: 2
                      truncated: false
                      limit: 20
                      dataSourceIds:
                        - 665f1c2ab3e77d0c9a1b4d21
                    rendered: >-
                      {"rawStatement":"SELECT count() AS count, language FROM
                      files GROUP BY language LIMIT
                      20","columns":["count","language"],"rows":[{"count":214,"language":"python"},{"count":32,"language":"markdown"}],"returnedRows":2,"limit":20}
                json_only:
                  summary: JSON success response
                  description: Returned when output_format is json.
                  value:
                    obj:
                      rawStatement: >-
                        SELECT count() AS count, language FROM files GROUP BY
                        language LIMIT 20
                      version: V1
                      resultShape: GroupedAggregate
                      columns:
                        - count
                        - language
                      rows:
                        - count: 214
                          language: python
                        - count: 32
                          language: markdown
                      returnedRows: 2
                      truncated: false
                      limit: 20
                      dataSourceIds:
                        - 665f1c2ab3e77d0c9a1b4d21
                agentic_only:
                  summary: Agent-facing success response
                  description: Returned when output_format is agentic.
                  value:
                    rendered: >-
                      {"rawStatement":"SELECT count() AS count, language FROM
                      files GROUP BY language LIMIT
                      20","columns":["count","language"],"rows":[{"count":214,"language":"python"},{"count":32,"language":"markdown"}],"returnedRows":2,"limit":20}
                repairable_error:
                  summary: Repairable tool error
                  description: >-
                    Returned with HTTP 200 when arguments can be corrected and
                    retried.
                  value:
                    obj:
                      error:
                        code: unknown_argument
                        message: >-
                          Unknown JSON argument(s) are not accepted in Tool API
                          v3: search_mode.
                        retry: >-
                          yes - repair the tool arguments and call the tool
                          again
                        try: >-
                          Use only the canonical arguments documented for this
                          tool.
                    rendered: |
                      <tool_error>
                        <code>unknown_argument</code>
                        <message>Unknown JSON argument(s) are not accepted in Tool API v3: search_mode.</message>
                        <retry>yes - repair the tool arguments and call the tool again</retry>
                        <try>Use only the canonical arguments documented for this tool.</try>
                      </tool_error>
            text/json:
              schema:
                $ref: '#/components/schemas/ToolApiEnvelope'
        '400':
          description: >-
            Bad request, including malformed JSON, unknown output_format, or
            invalid transport-level input.
        '401':
          description: Authentication failed or API key is missing.
        '403':
          description: >-
            The caller is not authorized for the requested data source or plan
            feature.
        '429':
          description: Rate limit, quota, or plan limit exceeded.
        '500':
          description: Unexpected server failure.
components:
  schemas:
    ArtifactMetadataQueryToolRequest:
      required:
        - statement
      type: object
      properties:
        output_format:
          enum:
            - json
            - agentic
          type:
            - 'null'
            - string
          description: >-
            Optional success projection. Omit to return both obj and rendered;
            use json for obj only; use agentic for rendered text only.
            Repairable errors always return both obj.error and rendered.
        statement:
          type:
            - 'null'
            - string
          description: >-
            One read-only ArtifactQuery statement. Use get_artifact_query_schema
            for supported entities, fields, and examples.
        data_sources:
          type:
            - 'null'
            - array
          items:
            type: string
          description: >-
            Repository or workspace names returned by get_data_sources. Omit
            only when the API key has a single unambiguous scope.
      additionalProperties: false
    ArtifactQueryExecutionResultDto:
      required:
        - columns
        - dataSourceIds
        - limit
        - rawStatement
        - resultShape
        - returnedRows
        - rows
      type: object
      properties:
        rawStatement:
          type:
            - 'null'
            - string
          description: Validated statement that was executed.
        version:
          $ref: '#/components/schemas/ArtifactQueryVersionDto'
          description: ArtifactQuery language version.
        resultShape:
          $ref: '#/components/schemas/ArtifactQueryResultShapeDto'
          description: Rows, Aggregate, or GroupedAggregate.
        columns:
          type:
            - 'null'
            - array
          items:
            type: string
          description: Column names in row order.
        rows:
          type:
            - 'null'
            - array
          items:
            type: object
            additionalProperties: {}
          description: Rows keyed by columns; value types depend on the projection.
        returnedRows:
          type: integer
          description: Number of returned rows.
          format: int32
        truncated:
          type: boolean
          description: Whether the payload budget omitted rows.
        limit:
          type: integer
          description: Effective LIMIT value.
          format: int32
        dataSourceIds:
          type:
            - 'null'
            - array
          items:
            type: string
          description: Resolved data sources queried.
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ToolApiWarning'
          description: >-
            Compatibility warnings, such as accepted deprecated argument
            aliases.
      additionalProperties: false
    ToolApiRepairableResult:
      required:
        - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ToolApiRepairableError'
          description: Structured error details used to repair the request and retry.
        warnings:
          type:
            - 'null'
            - array
          items:
            $ref: '#/components/schemas/ToolApiWarning'
          description: Compatibility warnings emitted before the request failed.
      additionalProperties: false
      description: >-
        Repairable failure returned with HTTP 200 so an agent can correct the
        request and retry.
    ToolApiEnvelope:
      type: object
      properties:
        obj:
          description: >-
            Arbitrary JSON result for the tool. Present for omitted/json success
            projections and every repairable error.
        rendered:
          type:
            - 'null'
            - string
          description: >-
            Agent-facing result text. Present for omitted/agentic success
            projections and every repairable error.
      additionalProperties: false
    ArtifactQueryVersionDto:
      enum:
        - V1
      type: string
    ArtifactQueryResultShapeDto:
      enum:
        - Rows
        - Aggregate
        - GroupedAggregate
      type: string
    ToolApiWarning:
      type: object
      properties:
        code:
          type:
            - 'null'
            - string
          description: Stable machine-readable warning code.
        message:
          type:
            - 'null'
            - string
          description: Human-readable compatibility warning.
        alias:
          type:
            - 'null'
            - string
          description: Deprecated argument alias that was accepted.
        canonical:
          type:
            - 'null'
            - string
          description: Canonical argument name to use instead of the alias.
      additionalProperties: false
    ToolApiRepairableError:
      type: object
      properties:
        code:
          type:
            - 'null'
            - string
          description: Stable machine-readable error code.
        message:
          type:
            - 'null'
            - string
          description: Human-readable explanation of the invalid request.
        retry:
          type:
            - 'null'
            - string
          description: Whether the caller should correct the request and retry.
        try:
          type:
            - 'null'
            - string
          description: Concrete guidance for repairing the next request.
      additionalProperties: false
  securitySchemes:
    ApiKeyScheme:
      type: http
      description: >-
        API Key authentication using Bearer token. Example: "Authorization:
        Bearer {apiKey}"
      scheme: bearer
      bearerFormat: API Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.