> ## 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.

# Get ArtifactQuery schema

> Returns the ArtifactQuery v1 catalog: queryable entities, fields, operators, relationships, limits, and example statements. Call it before composing a non-trivial `query_artifact_metadata` statement, or after a validation error, to get exact field names and supported operators.



## OpenAPI

````yaml /openapi-tool-api-v3.json post /api/tools/get_artifact_query_schema
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/get_artifact_query_schema:
    post:
      tags:
        - ToolApi
      summary: Get ArtifactQuery schema
      description: >-
        Returns the ArtifactQuery v1 catalog: queryable entities, fields,
        operators, relationships, limits, and example statements. Call it before
        composing a non-trivial `query_artifact_metadata` statement, or after a
        validation error, to get exact field names and supported operators.
      operationId: ToolApiGetArtifactQuerySchema
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArtifactQuerySchemaToolRequest'
            example:
              entity: files
              include_examples: true
          text/json:
            schema:
              $ref: '#/components/schemas/ArtifactQuerySchemaToolRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ArtifactQuerySchemaToolRequest'
      responses:
        '200':
          description: >-
            Success envelope. obj is the ArtifactQuery catalog: dsl_version,
            entities, fields, relationships, operators, required_limit, and
            examples; 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:
                $ref: '#/components/schemas/ToolApiEnvelope'
              example:
                obj:
                  dsl_version: artifactquery/v1
                  entity: files
                  entities:
                    - files
                    - symbols
                    - functions
                  fields:
                    - path
                    - language
                    - lines
                    - complexity
                  relationships:
                    - outgoing_calls
                    - incoming_calls
                    - references
                  operators:
                    - '='
                    - '!='
                    - '>'
                    - '>='
                    - <
                    - <=
                    - IN
                  required_limit: true
                  examples:
                    - SELECT path, language, lines FROM files LIMIT 20
                    - >-
                      SELECT count() AS count, language FROM files GROUP BY
                      language LIMIT 20
                rendered: >-
                  {"dsl_version":"artifactquery/v1","entities":["files","symbols","functions"],"required_limit":true,"examples":["SELECT
                  path, language, lines FROM files LIMIT 20"]}
            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:
    ArtifactQuerySchemaToolRequest:
      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.
        entity:
          type:
            - 'null'
            - string
          description: >-
            Optional ArtifactQuery entity to describe, such as files or symbols.
            Omit for the full schema.
        include_examples:
          type:
            - 'null'
            - boolean
          description: Include example ArtifactQuery statements. Default is true.
      additionalProperties: false
    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
  securitySchemes:
    ApiKeyScheme:
      type: http
      description: >-
        API Key authentication using Bearer token. Example: "Authorization:
        Bearer {apiKey}"
      scheme: bearer
      bearerFormat: API Key

````