> ## 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 repository file tree

> Returns a bounded directory tree for one repository, with short generated summaries for files and folders. Use it for structural orientation when you need to see how a repository (or one directory) is laid out; bound the response with `max_depth` and `max_nodes`. For concept questions prefer `semantic_search` — a folder whose name matches a concept is one candidate, not the whole story.



## OpenAPI

````yaml /openapi-tool-api-v3.json post /api/tools/get_file_tree
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_file_tree:
    post:
      tags:
        - ToolApi
      summary: Get repository file tree
      description: >-
        Returns a bounded directory tree for one repository, with short
        generated summaries for files and folders. Use it for structural
        orientation when you need to see how a repository (or one directory) is
        laid out; bound the response with `max_depth` and `max_nodes`. For
        concept questions prefer `semantic_search` — a folder whose name matches
        a concept is one candidate, not the whole story.
      operationId: ToolApiGetFileTree
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileTreeToolRequest'
            example:
              data_source: CodeAlive-AI/agent-framework
              max_depth: 3
          text/json:
            schema:
              $ref: '#/components/schemas/FileTreeToolRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/FileTreeToolRequest'
      responses:
        '200':
          description: >-
            Success envelope. obj contains trees[] (one per resolved repository)
            with a rendered tree string and a hint; 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:
                  trees:
                    - dataSource:
                        type: Repository
                        name: agent-framework
                      fullName: CodeAlive-AI/agent-framework
                      path: .
                      found: true
                      tree: |-
                        src/ — core packages
                          executor.py — task execution loop
                          scheduler.py — queue draining
                        tests/ — pytest suite
                  hint: Use read_file or fetch_artifacts to open specific files.
                rendered: >-
                  {"trees":[{"dataSource":{"type":"Repository","name":"agent-framework"},"fullName":"CodeAlive-AI/agent-framework","path":".","found":true,"tree":"src/
                  — core packages\n  executor.py — task execution loop\n 
                  scheduler.py — queue draining\ntests/ — pytest
                  suite"}],"hint":"Use read_file or fetch_artifacts to open
                  specific files."}
            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:
    FileTreeToolRequest:
      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.
        data_source:
          type:
            - 'null'
            - string
          description: >-
            One repository name or id returned by get_data_sources. Required
            when more than one repository is visible.
        path:
          type:
            - 'null'
            - string
          description: >-
            Optional repository-relative directory path. Omit for repository
            root.
        max_depth:
          type:
            - 'null'
            - integer
          description: Optional traversal depth limit.
          format: int32
        max_nodes:
          type:
            - 'null'
            - integer
          description: Optional maximum number of tree nodes to return.
          format: int32
        output_depth:
          type:
            - 'null'
            - integer
          description: Optional rendered output depth limit.
          format: int32
      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

````