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

# Read a repository file

> Reads one file by its exact repository-relative path, returning line-numbered content. This is the fallback reader: when a previous search already returned an artifact `identifier` for the file, prefer `fetch_artifacts`. Bound large files with `start_line`/`end_line`. When the path does not resolve, the response includes candidate paths with the same file name so the call can be repaired.



## OpenAPI

````yaml /openapi-tool-api-v3.json post /api/tools/read_file
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/read_file:
    post:
      tags:
        - ToolApi
      summary: Read a repository file
      description: >-
        Reads one file by its exact repository-relative path, returning
        line-numbered content. This is the fallback reader: when a previous
        search already returned an artifact `identifier` for the file, prefer
        `fetch_artifacts`. Bound large files with `start_line`/`end_line`. When
        the path does not resolve, the response includes candidate paths with
        the same file name so the call can be repaired.
      operationId: ToolApiReadFile
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadFileToolRequest'
            example:
              data_source: CodeAlive-AI/agent-framework
              path: README.md
          text/json:
            schema:
              $ref: '#/components/schemas/ReadFileToolRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ReadFileToolRequest'
      responses:
        '200':
          description: >-
            Success envelope. obj has found, files[] with line-numbered content
            (numberedContent, startLine, endLine), same-name candidates when the
            path did not resolve, 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:
                  found: true
                  files:
                    - identifier: CodeAlive-AI/agent-framework::README.md
                      path: README.md
                      dataSource:
                        type: Repository
                        name: agent-framework
                      fullName: CodeAlive-AI/agent-framework
                      startLine: 1
                      endLine: 2
                      contentByteSize: 96
                      numberedContent: |-
                        1: # Agent Framework
                        2: Multi-agent orchestration framework.
                  candidates: []
                  sameNameCandidates: []
                  sameNameTotalCount: 0
                  hint: >-
                    Content is line-numbered; request start_line/end_line ranges
                    for large files.
                rendered: >-
                  {"found":true,"files":[{"identifier":"CodeAlive-AI/agent-framework::README.md","path":"README.md","startLine":1,"endLine":2,"numberedContent":"1:
                  # Agent Framework\n2: Multi-agent orchestration
                  framework."}],"hint":"Content is line-numbered; request
                  start_line/end_line ranges for large 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:
    ReadFileToolRequest:
      required:
        - path
      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: >-
            Repository-relative file path returned by get_file_tree,
            semantic_search, or grep_search.
        start_line:
          type:
            - 'null'
            - integer
          description: Optional 1-based start line.
          format: int32
        end_line:
          type:
            - 'null'
            - integer
          description: Optional 1-based end line.
          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

````