{ "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" } ], "paths": { "/api/tools/get_data_sources": { "post": { "tags": [ "ToolApi" ], "summary": "List visible data sources", "description": "Lists the repositories and workspaces visible to the calling API key, including readiness state. Call this first: every other tool accepts the returned `name` values in its `data_sources`/`data_source` argument (use `id` only for automation or to disambiguate duplicate names). Pass an optional `query` to rank sources by relevance to a question; the call is billed only when relevance ranking actually runs.", "operationId": "ToolApiGetDataSources", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDataSourcesToolRequest" }, "example": { "query": "agent framework" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetDataSourcesToolRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GetDataSourcesToolRequest" } } } }, "responses": { "200": { "description": "Success envelope. obj contains data_sources (visible sources with id, name, fullName, readiness), relevance_status (not_requested | skipped | failed_open | succeeded), total_available, billed, and a usage hint; rendered is a compact XML block for agents. 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 block; repair the arguments and retry.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "obj", "rendered" ], "type": "object", "properties": { "obj": { "$ref": "#/components/schemas/GetDataSourcesToolResponse" }, "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/GetDataSourcesToolResponse" } }, "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": { "data_sources": [ { "type": "Repository", "id": "665f1c2ab3e77d0c9a1b4d21", "name": "agent-framework", "fullName": "CodeAlive-AI/agent-framework", "description": "Multi-agent orchestration framework.", "readiness": "Ready" } ], "relevance_status": "succeeded", "total_available": 3, "billed": true, "hint": "Use the name value returned here for data_sources/data_source. Use id for automation or explicit disambiguation." }, "rendered": "\n \n\nUse the name attribute for data_sources/data_source unless automation needs id." } }, "json_only": { "summary": "JSON success response", "description": "Returned when output_format is json.", "value": { "obj": { "data_sources": [ { "type": "Repository", "id": "665f1c2ab3e77d0c9a1b4d21", "name": "agent-framework", "fullName": "CodeAlive-AI/agent-framework", "description": "Multi-agent orchestration framework.", "readiness": "Ready" } ], "relevance_status": "succeeded", "total_available": 3, "billed": true, "hint": "Use the name value returned here for data_sources/data_source. Use id for automation or explicit disambiguation." } } }, "agentic_only": { "summary": "Agent-facing success response", "description": "Returned when output_format is agentic.", "value": { "rendered": "\n \n\nUse the name attribute for data_sources/data_source unless automation needs id." } }, "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": "\n unknown_argument\n Unknown JSON argument(s) are not accepted in Tool API v3: search_mode.\n yes - repair the tool arguments and call the tool again\n Use only the canonical arguments documented for this tool.\n\n" } } } }, "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." } }, "x-codealive-tool-name": "get_data_sources", "x-codealive-mcp-name": "get_data_sources", "x-codealive-output-formats": [ "json", "agentic" ], "x-codealive-billing": "conditional", "x-codealive-read-only": true, "x-codealive-deprecated-aliases": [ "alive_only" ], "x-codealive-examples": { "request": { "query": "agent framework" }, "response": { "obj": { "data_sources": [ { "type": "Repository", "id": "665f1c2ab3e77d0c9a1b4d21", "name": "agent-framework", "fullName": "CodeAlive-AI/agent-framework", "description": "Multi-agent orchestration framework.", "readiness": "Ready" } ], "relevance_status": "succeeded", "total_available": 3, "billed": true, "hint": "Use the name value returned here for data_sources/data_source. Use id for automation or explicit disambiguation." }, "rendered": "\n \n\nUse the name attribute for data_sources/data_source unless automation needs id." } } } }, "/api/tools/semantic_search": { "post": { "tags": [ "ToolApi" ], "summary": "Semantic search", "description": "Searches indexed code by meaning rather than by exact text. This is the default first tool for behaviour, intent, mechanism, and architecture questions. Phrase `question` as a full natural-language English sentence — \"How does task execution work?\", \"Where is retry handling implemented?\" — not as bare keywords; keyword strings sharply degrade recall. Keep identifiers and codebase-specific terms verbatim inside the sentence. For acronyms, exact names, error text, routes, or config keys, run `grep_search` alongside. Results carry stable artifact `identifier` values — pass them to `fetch_artifacts` to read the code, or to `get_artifact_relationships` to map callers and callees, before drawing conclusions from snippets.", "operationId": "ToolApiSemanticSearch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticSearchToolRequest" }, "example": { "question": "How does task execution work?", "data_sources": [ "CodeAlive-AI/agent-framework" ] } }, "text/json": { "schema": { "$ref": "#/components/schemas/SemanticSearchToolRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/SemanticSearchToolRequest" } } } }, "responses": { "200": { "description": "Success envelope. obj is the result set: results[] with identifier, kind, dataSource, location.path plus line range, relevance score, and a short description/snippet; rendered is a XML block with a follow-up hint. 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 block; repair the arguments and retry.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "obj", "rendered" ], "type": "object", "properties": { "obj": { "$ref": "#/components/schemas/SearchResponse" }, "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/SearchResponse" } }, "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": { "results": [ { "kind": "method", "dataSource": { "type": "Repository", "id": "665f1c2ab3e77d0c9a1b4d21", "name": "agent-framework" }, "identifier": "CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run", "location": { "path": "src/executor.py", "range": { "start": { "line": 42, "character": 0 }, "end": { "line": 88, "character": 0 } } }, "score": 0.91, "description": "Executes a queued task through retry and telemetry wrappers.", "contentByteSize": 2048 } ] }, "rendered": "\n Executes a queued task through retry and telemetry wrappers.\n\nFetch relevant identifiers with fetch_artifacts or read local files before drawing conclusions." } }, "json_only": { "summary": "JSON success response", "description": "Returned when output_format is json.", "value": { "obj": { "results": [ { "kind": "method", "dataSource": { "type": "Repository", "id": "665f1c2ab3e77d0c9a1b4d21", "name": "agent-framework" }, "identifier": "CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run", "location": { "path": "src/executor.py", "range": { "start": { "line": 42, "character": 0 }, "end": { "line": 88, "character": 0 } } }, "score": 0.91, "description": "Executes a queued task through retry and telemetry wrappers.", "contentByteSize": 2048 } ] } } }, "agentic_only": { "summary": "Agent-facing success response", "description": "Returned when output_format is agentic.", "value": { "rendered": "\n Executes a queued task through retry and telemetry wrappers.\n\nFetch relevant identifiers with fetch_artifacts or read local files before drawing conclusions." } }, "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": "\n unknown_argument\n Unknown JSON argument(s) are not accepted in Tool API v3: search_mode.\n yes - repair the tool arguments and call the tool again\n Use only the canonical arguments documented for this tool.\n\n" } } } }, "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." } }, "x-codealive-tool-name": "semantic_search", "x-codealive-mcp-name": "semantic_search", "x-codealive-output-formats": [ "json", "agentic" ], "x-codealive-billing": "always", "x-codealive-read-only": true, "x-codealive-deprecated-aliases": [ "query", "excludeMarkdown", "dataSourceNames", "data_source_names", "maxResults" ], "x-codealive-examples": { "request": { "question": "How does task execution work?", "data_sources": [ "CodeAlive-AI/agent-framework" ] }, "response": { "obj": { "results": [ { "kind": "method", "dataSource": { "type": "Repository", "id": "665f1c2ab3e77d0c9a1b4d21", "name": "agent-framework" }, "identifier": "CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run", "location": { "path": "src/executor.py", "range": { "start": { "line": 42, "character": 0 }, "end": { "line": 88, "character": 0 } } }, "score": 0.91, "description": "Executes a queued task through retry and telemetry wrappers.", "contentByteSize": 2048 } ] }, "rendered": "\n Executes a queued task through retry and telemetry wrappers.\n\nFetch relevant identifiers with fetch_artifacts or read local files before drawing conclusions." } } } }, "/api/tools/grep_search": { "post": { "tags": [ "ToolApi" ], "summary": "Grep search", "description": "Searches indexed code for exact literal text or a regular expression (set `regex` to `true`). First choice when you already know an exact symbol name, string literal, error message, route, or configuration key, and for exhaustive \"find every usage\" sweeps. It complements `semantic_search`: embeddings underrepresent rare short tokens such as acronyms (`JWT`, `OIDC`), so run `grep_search` on the exact token alongside a semantic query rather than instead of it.", "operationId": "ToolApiGrepSearch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrepSearchToolRequest" }, "example": { "query": "TaskExecutor", "data_sources": [ "CodeAlive-AI/agent-framework" ] } }, "text/json": { "schema": { "$ref": "#/components/schemas/GrepSearchToolRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GrepSearchToolRequest" } } } }, "responses": { "200": { "description": "Success envelope. obj.results[] adds grep specifics: matchCount and matches[] with lineNumber, column range, and lineText; rendered is a XML block. 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 block; repair the arguments and retry.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "obj", "rendered" ], "type": "object", "properties": { "obj": { "$ref": "#/components/schemas/GrepSearchResponse" }, "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/GrepSearchResponse" } }, "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": { "results": [ { "kind": "file", "dataSource": { "type": "Repository", "id": "665f1c2ab3e77d0c9a1b4d21", "name": "agent-framework" }, "identifier": "CodeAlive-AI/agent-framework::src/executor.py", "location": { "path": "src/executor.py", "range": { "start": { "line": 42, "character": 6 }, "end": { "line": 42, "character": 18 } } }, "startLine": 42, "endLine": 88, "score": 1, "contentByteSize": 2048, "matchCount": 2, "summary": "Executes queued tasks with retry and telemetry.", "matches": [ { "lineNumber": 42, "startColumn": 7, "endColumn": 18, "lineText": "class TaskExecutor:", "contextLines": [ { "lineNumber": 41, "lineText": "@instrumented" }, { "lineNumber": 42, "lineText": "class TaskExecutor:" }, { "lineNumber": 43, "lineText": " def run(self, task):" } ] } ] } ] }, "rendered": "\n \n\nFetch relevant identifiers with fetch_artifacts or read local files before drawing conclusions." } }, "json_only": { "summary": "JSON success response", "description": "Returned when output_format is json.", "value": { "obj": { "results": [ { "kind": "file", "dataSource": { "type": "Repository", "id": "665f1c2ab3e77d0c9a1b4d21", "name": "agent-framework" }, "identifier": "CodeAlive-AI/agent-framework::src/executor.py", "location": { "path": "src/executor.py", "range": { "start": { "line": 42, "character": 6 }, "end": { "line": 42, "character": 18 } } }, "startLine": 42, "endLine": 88, "score": 1, "contentByteSize": 2048, "matchCount": 2, "summary": "Executes queued tasks with retry and telemetry.", "matches": [ { "lineNumber": 42, "startColumn": 7, "endColumn": 18, "lineText": "class TaskExecutor:", "contextLines": [ { "lineNumber": 41, "lineText": "@instrumented" }, { "lineNumber": 42, "lineText": "class TaskExecutor:" }, { "lineNumber": 43, "lineText": " def run(self, task):" } ] } ] } ] } } }, "agentic_only": { "summary": "Agent-facing success response", "description": "Returned when output_format is agentic.", "value": { "rendered": "\n \n\nFetch relevant identifiers with fetch_artifacts or read local files before drawing conclusions." } }, "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": "\n unknown_argument\n Unknown JSON argument(s) are not accepted in Tool API v3: search_mode.\n yes - repair the tool arguments and call the tool again\n Use only the canonical arguments documented for this tool.\n\n" } } } }, "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." } }, "x-codealive-tool-name": "grep_search", "x-codealive-mcp-name": "grep_search", "x-codealive-output-formats": [ "json", "agentic" ], "x-codealive-billing": "always", "x-codealive-read-only": true, "x-codealive-deprecated-aliases": [ "excludeMarkdown", "dataSourceNames", "data_source_names", "maxResults" ], "x-codealive-examples": { "request": { "query": "TaskExecutor", "data_sources": [ "CodeAlive-AI/agent-framework" ] }, "response": { "obj": { "results": [ { "kind": "file", "dataSource": { "type": "Repository", "id": "665f1c2ab3e77d0c9a1b4d21", "name": "agent-framework" }, "identifier": "CodeAlive-AI/agent-framework::src/executor.py", "location": { "path": "src/executor.py", "range": { "start": { "line": 42, "character": 6 }, "end": { "line": 42, "character": 18 } } }, "startLine": 42, "endLine": 88, "score": 1, "contentByteSize": 2048, "matchCount": 2, "summary": "Executes queued tasks with retry and telemetry.", "matches": [ { "lineNumber": 42, "startColumn": 7, "endColumn": 18, "lineText": "class TaskExecutor:", "contextLines": [ { "lineNumber": 41, "lineText": "@instrumented" }, { "lineNumber": 42, "lineText": "class TaskExecutor:" }, { "lineNumber": 43, "lineText": " def run(self, task):" } ] } ] } ] }, "rendered": "\n \n\nFetch relevant identifiers with fetch_artifacts or read local files before drawing conclusions." } } } }, "/api/tools/get_repository_ontology": { "post": { "tags": [ "ToolApi" ], "summary": "Get repository ontology", "description": "Returns the generated high-level map (ontology) of one repository: its purpose, subsystems, key concepts, and how they relate. Use it to orient before focused searching when the repository is unfamiliar, or to decide which part of a large codebase a question lands in. Accepts exactly one repository — workspace names are rejected; pick a specific repository from `get_data_sources`.", "operationId": "ToolApiGetRepositoryOntology", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryToolRequest" }, "example": { "data_source": "CodeAlive-AI/agent-framework" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RepositoryToolRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/RepositoryToolRequest" } } } }, "responses": { "200": { "description": "Success envelope. obj is { repository_count, content } where content is the ontology Markdown; rendered is the same Markdown text. 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 block; repair the arguments and retry.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "obj", "rendered" ], "type": "object", "properties": { "obj": { "$ref": "#/components/schemas/RepositoryOntologyToolResponse" }, "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/RepositoryOntologyToolResponse" } }, "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": { "repository_count": 1, "content": "# agent-framework\n\n## Subsystems\n- Task execution — scheduling, retries, telemetry.\n- Transport — message bus adapters.\n" }, "rendered": "# agent-framework\n\n## Subsystems\n- Task execution — scheduling, retries, telemetry.\n- Transport — message bus adapters.\n" } }, "json_only": { "summary": "JSON success response", "description": "Returned when output_format is json.", "value": { "obj": { "repository_count": 1, "content": "# agent-framework\n\n## Subsystems\n- Task execution — scheduling, retries, telemetry.\n- Transport — message bus adapters.\n" } } }, "agentic_only": { "summary": "Agent-facing success response", "description": "Returned when output_format is agentic.", "value": { "rendered": "# agent-framework\n\n## Subsystems\n- Task execution — scheduling, retries, telemetry.\n- Transport — message bus adapters.\n" } }, "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": "\n unknown_argument\n Unknown JSON argument(s) are not accepted in Tool API v3: search_mode.\n yes - repair the tool arguments and call the tool again\n Use only the canonical arguments documented for this tool.\n\n" } } } }, "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." } }, "x-codealive-tool-name": "get_repository_ontology", "x-codealive-mcp-name": "get_repository_ontology", "x-codealive-output-formats": [ "json", "agentic" ], "x-codealive-billing": "always", "x-codealive-read-only": true, "x-codealive-deprecated-aliases": [ "dataSourceName", "data_source_name" ], "x-codealive-examples": { "request": { "data_source": "CodeAlive-AI/agent-framework" }, "response": { "obj": { "repository_count": 1, "content": "# agent-framework\n\n## Subsystems\n- Task execution — scheduling, retries, telemetry.\n- Transport — message bus adapters.\n" }, "rendered": "# agent-framework\n\n## Subsystems\n- Task execution — scheduling, retries, telemetry.\n- Transport — message bus adapters.\n" } } } }, "/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 block; repair the arguments and retry.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "obj", "rendered" ], "type": "object", "properties": { "obj": { "$ref": "#/components/schemas/AgentFileTreeToolResponse" }, "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/AgentFileTreeToolResponse" } }, "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": { "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." }, "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.\"}" } }, "json_only": { "summary": "JSON success response", "description": "Returned when output_format is json.", "value": { "obj": { "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." } } }, "agentic_only": { "summary": "Agent-facing success response", "description": "Returned when output_format is agentic.", "value": { "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.\"}" } }, "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": "\n unknown_argument\n Unknown JSON argument(s) are not accepted in Tool API v3: search_mode.\n yes - repair the tool arguments and call the tool again\n Use only the canonical arguments documented for this tool.\n\n" } } } }, "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." } }, "x-codealive-tool-name": "get_file_tree", "x-codealive-mcp-name": "get_file_tree", "x-codealive-output-formats": [ "json", "agentic" ], "x-codealive-billing": "never", "x-codealive-read-only": true, "x-codealive-deprecated-aliases": [ "dataSourceName", "data_source_name", "maxDepth", "maxNodes", "outputDepth" ], "x-codealive-examples": { "request": { "data_source": "CodeAlive-AI/agent-framework", "max_depth": 3 }, "response": { "obj": { "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." }, "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.\"}" } } } }, "/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 block; repair the arguments and retry.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "obj", "rendered" ], "type": "object", "properties": { "obj": { "$ref": "#/components/schemas/AgentReadFileToolResponse" }, "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/AgentReadFileToolResponse" } }, "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": { "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\n2: 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.\"}" } }, "json_only": { "summary": "JSON success response", "description": "Returned when output_format is json.", "value": { "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\n2: Multi-agent orchestration framework." } ], "candidates": [], "sameNameCandidates": [], "sameNameTotalCount": 0, "hint": "Content is line-numbered; request start_line/end_line ranges for large files." } } }, "agentic_only": { "summary": "Agent-facing success response", "description": "Returned when output_format is agentic.", "value": { "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.\"}" } }, "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": "\n unknown_argument\n Unknown JSON argument(s) are not accepted in Tool API v3: search_mode.\n yes - repair the tool arguments and call the tool again\n Use only the canonical arguments documented for this tool.\n\n" } } } }, "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." } }, "x-codealive-tool-name": "read_file", "x-codealive-mcp-name": "read_file", "x-codealive-output-formats": [ "json", "agentic" ], "x-codealive-billing": "never", "x-codealive-read-only": true, "x-codealive-deprecated-aliases": [ "dataSourceName", "data_source_name", "startLine", "endLine" ], "x-codealive-examples": { "request": { "data_source": "CodeAlive-AI/agent-framework", "path": "README.md" }, "response": { "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\n2: 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.\"}" } } } }, "/api/tools/fetch_artifacts": { "post": { "tags": [ "ToolApi" ], "summary": "Fetch artifacts", "description": "Fetches full content for up to 50 known artifact identifiers (`repository::path` or `repository::path::symbol`) returned by `semantic_search`, `grep_search`, `read_file`, or `get_artifact_relationships`. This is the preferred way to read code once an identifier is known — do not split the identifier back into a repository and path for `read_file`. Responses include relationship previews (caller/callee counts) that suggest the next traversal step.", "operationId": "ToolApiFetchArtifacts", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchArtifactsToolRequest" }, "example": { "identifiers": [ "CodeAlive-AI/agent-framework::README.md" ] } }, "text/json": { "schema": { "$ref": "#/components/schemas/FetchArtifactsToolRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FetchArtifactsToolRequest" } } } }, "responses": { "200": { "description": "Success envelope. obj.artifacts[] returns each requested identifier with found, content, contentByteSize, startLine, and a relationships preview (caller/callee counts); 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 block; repair the arguments and retry.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "obj", "rendered" ], "type": "object", "properties": { "obj": { "$ref": "#/components/schemas/ArtifactContentResponse" }, "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/ArtifactContentResponse" } }, "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": { "artifacts": [ { "identifier": "CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run", "found": true, "content": "def run(self, task):\n with self._telemetry.span(task):\n return self._retry(task)", "contentByteSize": 2048, "startLine": 42, "relationships": { "incomingCallsCount": 2, "incomingCalls": [ { "identifier": "CodeAlive-AI/agent-framework::src/scheduler.py::Scheduler.tick", "summary": "Drains the queue and dispatches due tasks." } ] } } ], "hint": "Use get_artifact_relationships to expand callers or callees." }, "rendered": "{\"artifacts\":[{\"identifier\":\"CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run\",\"found\":true,\"content\":\"def run(self, task): ...\",\"startLine\":42}],\"hint\":\"Use get_artifact_relationships to expand callers or callees.\"}" } }, "json_only": { "summary": "JSON success response", "description": "Returned when output_format is json.", "value": { "obj": { "artifacts": [ { "identifier": "CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run", "found": true, "content": "def run(self, task):\n with self._telemetry.span(task):\n return self._retry(task)", "contentByteSize": 2048, "startLine": 42, "relationships": { "incomingCallsCount": 2, "incomingCalls": [ { "identifier": "CodeAlive-AI/agent-framework::src/scheduler.py::Scheduler.tick", "summary": "Drains the queue and dispatches due tasks." } ] } } ], "hint": "Use get_artifact_relationships to expand callers or callees." } } }, "agentic_only": { "summary": "Agent-facing success response", "description": "Returned when output_format is agentic.", "value": { "rendered": "{\"artifacts\":[{\"identifier\":\"CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run\",\"found\":true,\"content\":\"def run(self, task): ...\",\"startLine\":42}],\"hint\":\"Use get_artifact_relationships to expand callers or callees.\"}" } }, "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": "\n unknown_argument\n Unknown JSON argument(s) are not accepted in Tool API v3: search_mode.\n yes - repair the tool arguments and call the tool again\n Use only the canonical arguments documented for this tool.\n\n" } } } }, "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." } }, "x-codealive-tool-name": "fetch_artifacts", "x-codealive-mcp-name": "fetch_artifacts", "x-codealive-output-formats": [ "json", "agentic" ], "x-codealive-billing": "never", "x-codealive-read-only": true, "x-codealive-deprecated-aliases": [ "dataSourceName", "data_source_name" ], "x-codealive-examples": { "request": { "identifiers": [ "CodeAlive-AI/agent-framework::README.md" ] }, "response": { "obj": { "artifacts": [ { "identifier": "CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run", "found": true, "content": "def run(self, task):\n with self._telemetry.span(task):\n return self._retry(task)", "contentByteSize": 2048, "startLine": 42, "relationships": { "incomingCallsCount": 2, "incomingCalls": [ { "identifier": "CodeAlive-AI/agent-framework::src/scheduler.py::Scheduler.tick", "summary": "Drains the queue and dispatches due tasks." } ] } } ], "hint": "Use get_artifact_relationships to expand callers or callees." }, "rendered": "{\"artifacts\":[{\"identifier\":\"CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run\",\"found\":true,\"content\":\"def run(self, task): ...\",\"startLine\":42}],\"hint\":\"Use get_artifact_relationships to expand callers or callees.\"}" } } } }, "/api/tools/get_artifact_relationships": { "post": { "tags": [ "ToolApi" ], "summary": "Get artifact relationships", "description": "Traverses the code graph around one known artifact: callers, callees, inheritance, and references. Choose `profile` by the question: `calls_only` (default) for call edges of functions and methods, `inheritance_only` for base types and implementations, `references_only` for where-used checks on types, fields, events, and other non-call usage, `all_relevant` for calls plus inheritance. Use it to find upstream entry points and downstream consumers before reading more files.", "operationId": "ToolApiGetArtifactRelationships", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactRelationshipsToolRequest" }, "example": { "identifier": "CodeAlive-AI/agent-framework::src/foo.py::Foo.run", "profile": "calls_only" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ArtifactRelationshipsToolRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ArtifactRelationshipsToolRequest" } } } }, "responses": { "200": { "description": "Success envelope. obj describes the traversal: sourceIdentifier, profile, found, relationships[] grouped by relationType with items[] (identifier, filePath, startLine, shortSummary) and truncation flags, plus availableRelationshipCounts; 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 block; repair the arguments and retry.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "obj", "rendered" ], "type": "object", "properties": { "obj": { "$ref": "#/components/schemas/ArtifactRelationshipsResponse" }, "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/ArtifactRelationshipsResponse" } }, "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": { "sourceIdentifier": "CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run", "profile": "CallsOnly", "found": true, "relationships": [ { "relationType": "IncomingCalls", "totalCount": 2, "returnedCount": 2, "truncated": false, "items": [ { "identifier": "CodeAlive-AI/agent-framework::src/scheduler.py::Scheduler.tick", "filePath": "src/scheduler.py", "startLine": 17, "shortSummary": "Drains the queue and dispatches due tasks." } ] } ], "availableRelationshipCounts": { "outgoingCalls": 3, "incomingCalls": 2, "ancestors": 0, "descendants": 0, "references": 5 } }, "rendered": "{\"sourceIdentifier\":\"CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run\",\"profile\":\"CallsOnly\",\"found\":true,\"relationships\":[{\"relationType\":\"IncomingCalls\",\"totalCount\":2,\"items\":[{\"identifier\":\"CodeAlive-AI/agent-framework::src/scheduler.py::Scheduler.tick\",\"filePath\":\"src/scheduler.py\",\"startLine\":17}]}]}" } }, "json_only": { "summary": "JSON success response", "description": "Returned when output_format is json.", "value": { "obj": { "sourceIdentifier": "CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run", "profile": "CallsOnly", "found": true, "relationships": [ { "relationType": "IncomingCalls", "totalCount": 2, "returnedCount": 2, "truncated": false, "items": [ { "identifier": "CodeAlive-AI/agent-framework::src/scheduler.py::Scheduler.tick", "filePath": "src/scheduler.py", "startLine": 17, "shortSummary": "Drains the queue and dispatches due tasks." } ] } ], "availableRelationshipCounts": { "outgoingCalls": 3, "incomingCalls": 2, "ancestors": 0, "descendants": 0, "references": 5 } } } }, "agentic_only": { "summary": "Agent-facing success response", "description": "Returned when output_format is agentic.", "value": { "rendered": "{\"sourceIdentifier\":\"CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run\",\"profile\":\"CallsOnly\",\"found\":true,\"relationships\":[{\"relationType\":\"IncomingCalls\",\"totalCount\":2,\"items\":[{\"identifier\":\"CodeAlive-AI/agent-framework::src/scheduler.py::Scheduler.tick\",\"filePath\":\"src/scheduler.py\",\"startLine\":17}]}]}" } }, "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": "\n unknown_argument\n Unknown JSON argument(s) are not accepted in Tool API v3: search_mode.\n yes - repair the tool arguments and call the tool again\n Use only the canonical arguments documented for this tool.\n\n" } } } }, "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." } }, "x-codealive-tool-name": "get_artifact_relationships", "x-codealive-mcp-name": "get_artifact_relationships", "x-codealive-output-formats": [ "json", "agentic" ], "x-codealive-billing": "never", "x-codealive-read-only": true, "x-codealive-deprecated-aliases": [ "dataSourceName", "data_source_name", "maxCountPerType" ], "x-codealive-examples": { "request": { "identifier": "CodeAlive-AI/agent-framework::src/foo.py::Foo.run", "profile": "calls_only" }, "response": { "obj": { "sourceIdentifier": "CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run", "profile": "CallsOnly", "found": true, "relationships": [ { "relationType": "IncomingCalls", "totalCount": 2, "returnedCount": 2, "truncated": false, "items": [ { "identifier": "CodeAlive-AI/agent-framework::src/scheduler.py::Scheduler.tick", "filePath": "src/scheduler.py", "startLine": 17, "shortSummary": "Drains the queue and dispatches due tasks." } ] } ], "availableRelationshipCounts": { "outgoingCalls": 3, "incomingCalls": 2, "ancestors": 0, "descendants": 0, "references": 5 } }, "rendered": "{\"sourceIdentifier\":\"CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run\",\"profile\":\"CallsOnly\",\"found\":true,\"relationships\":[{\"relationType\":\"IncomingCalls\",\"totalCount\":2,\"items\":[{\"identifier\":\"CodeAlive-AI/agent-framework::src/scheduler.py::Scheduler.tick\",\"filePath\":\"src/scheduler.py\",\"startLine\":17}]}]}" } } } }, "/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 block; repair the arguments and retry.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "obj", "rendered" ], "type": "object", "properties": { "obj": { "$ref": "#/components/schemas/ArtifactQuerySchemaToolResponse" }, "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/ArtifactQuerySchemaToolResponse" } }, "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": { "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\"]}" } }, "json_only": { "summary": "JSON success response", "description": "Returned when output_format is json.", "value": { "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" ] } } }, "agentic_only": { "summary": "Agent-facing success response", "description": "Returned when output_format is agentic.", "value": { "rendered": "{\"dsl_version\":\"artifactquery/v1\",\"entities\":[\"files\",\"symbols\",\"functions\"],\"required_limit\":true,\"examples\":[\"SELECT path, language, lines FROM files 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": "\n unknown_argument\n Unknown JSON argument(s) are not accepted in Tool API v3: search_mode.\n yes - repair the tool arguments and call the tool again\n Use only the canonical arguments documented for this tool.\n\n" } } } }, "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." } }, "x-codealive-tool-name": "get_artifact_query_schema", "x-codealive-mcp-name": "get_artifact_query_schema", "x-codealive-output-formats": [ "json", "agentic" ], "x-codealive-billing": "never", "x-codealive-read-only": true, "x-codealive-deprecated-aliases": [ "includeExamples" ], "x-codealive-examples": { "request": { "entity": "files", "include_examples": true }, "response": { "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\"]}" } } } }, "/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 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": "\n unknown_argument\n Unknown JSON argument(s) are not accepted in Tool API v3: search_mode.\n yes - repair the tool arguments and call the tool again\n Use only the canonical arguments documented for this tool.\n\n" } } } }, "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." } }, "x-codealive-tool-name": "query_artifact_metadata", "x-codealive-mcp-name": "query_artifact_metadata", "x-codealive-output-formats": [ "json", "agentic" ], "x-codealive-billing": "always", "x-codealive-read-only": true, "x-codealive-deprecated-aliases": [ "dataSourceNames", "data_source_names" ], "x-codealive-examples": { "request": { "statement": "SELECT path, language FROM files LIMIT 20", "data_sources": [ "CodeAlive-AI/agent-framework" ] }, "response": { "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}" } } } }, "/api/tools/chat": { "post": { "tags": [ "ToolApi" ], "summary": "Stateless chat", "description": "Asks CodeAlive's built-in research agent a question and returns a synthesized, evidence-grounded answer. Each call is stateless: no conversation is stored, so include all relevant prior findings, artifact identifiers, constraints, and scope in `question`. This is the highest-latency, highest-cost tool — when orchestrating your own agent loop, prefer the direct search and read tools and reserve `chat` for when a delegated end-to-end answer is explicitly wanted.", "operationId": "ToolApiChat", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatToolRequest" }, "example": { "question": "Summarize how task execution works. Prior context: none.", "data_sources": [ "CodeAlive-AI/agent-framework" ] } }, "text/json": { "schema": { "$ref": "#/components/schemas/ChatToolRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ChatToolRequest" } } } }, "responses": { "200": { "description": "Success envelope. obj is { answer, stateless: true, hint }; rendered is the answer text itself. 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 block; repair the arguments and retry.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "obj", "rendered" ], "type": "object", "properties": { "obj": { "$ref": "#/components/schemas/ChatToolResponse" }, "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/ChatToolResponse" } }, "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": { "answer": "Task execution starts in `Scheduler.tick` (src/scheduler.py), which drains the queue and dispatches each due task to `TaskExecutor.run` …", "stateless": true, "hint": "Tool API v3 chat does not preserve public conversation context. Include prior findings, identifiers, assumptions, scope, and constraints in each question." }, "rendered": "Task execution starts in `Scheduler.tick` (src/scheduler.py), which drains the queue and dispatches each due task to `TaskExecutor.run` …" } }, "json_only": { "summary": "JSON success response", "description": "Returned when output_format is json.", "value": { "obj": { "answer": "Task execution starts in `Scheduler.tick` (src/scheduler.py), which drains the queue and dispatches each due task to `TaskExecutor.run` …", "stateless": true, "hint": "Tool API v3 chat does not preserve public conversation context. Include prior findings, identifiers, assumptions, scope, and constraints in each question." } } }, "agentic_only": { "summary": "Agent-facing success response", "description": "Returned when output_format is agentic.", "value": { "rendered": "Task execution starts in `Scheduler.tick` (src/scheduler.py), which drains the queue and dispatches each due task to `TaskExecutor.run` …" } }, "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": "\n unknown_argument\n Unknown JSON argument(s) are not accepted in Tool API v3: search_mode.\n yes - repair the tool arguments and call the tool again\n Use only the canonical arguments documented for this tool.\n\n" } } } }, "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." } }, "x-codealive-tool-name": "chat", "x-codealive-mcp-name": "chat", "x-codealive-output-formats": [ "json", "agentic" ], "x-codealive-billing": "always", "x-codealive-read-only": true, "x-codealive-deprecated-aliases": [ "dataSourceNames", "data_source_names" ], "x-codealive-examples": { "request": { "question": "Summarize how task execution works. Prior context: none.", "data_sources": [ "CodeAlive-AI/agent-framework" ] }, "response": { "obj": { "answer": "Task execution starts in `Scheduler.tick` (src/scheduler.py), which drains the queue and dispatches each due task to `TaskExecutor.run` …", "stateless": true, "hint": "Tool API v3 chat does not preserve public conversation context. Include prior findings, identifiers, assumptions, scope, and constraints in each question." }, "rendered": "Task execution starts in `Scheduler.tick` (src/scheduler.py), which drains the queue and dispatches each due task to `TaskExecutor.run` …" } } } } }, "components": { "schemas": { "AgentFileTreeItem": { "type": "object", "properties": { "dataSource": { "description": "Resolved repository reference.", "$ref": "#/components/schemas/AgentToolDataSourceRef" }, "fullName": { "type": [ "null", "string" ], "description": "Owner-qualified repository name." }, "path": { "type": [ "null", "string" ], "description": "Repository-relative tree root." }, "found": { "type": "boolean", "description": "Whether the requested path exists." }, "tree": { "type": [ "null", "string" ], "description": "Rendered bounded directory tree." } }, "additionalProperties": false }, "AgentFileTreeToolResponse": { "required": [ "hint" ], "type": "object", "properties": { "trees": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AgentFileTreeItem" }, "description": "One tree for the resolved repository." }, "hint": { "type": [ "null", "string" ], "description": "Suggested next tool call." }, "error": { "description": "Recoverable file-tree error, when applicable.", "$ref": "#/components/schemas/AgentToolError" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApiWarning" }, "description": "Compatibility warnings, such as accepted deprecated argument aliases." } }, "additionalProperties": false }, "AgentReadFileCandidate": { "type": "object", "properties": { "identifier": { "type": [ "null", "string" ], "description": "Stable candidate file identifier." }, "path": { "type": [ "null", "string" ], "description": "Repository-relative candidate path." }, "dataSource": { "description": "Candidate repository reference.", "$ref": "#/components/schemas/AgentToolDataSourceRef" }, "fullName": { "type": [ "null", "string" ], "description": "Owner-qualified repository name." } }, "additionalProperties": false }, "AgentReadFileContent": { "type": "object", "properties": { "identifier": { "type": [ "null", "string" ], "description": "Stable file artifact identifier." }, "path": { "type": [ "null", "string" ], "description": "Repository-relative file path." }, "dataSource": { "description": "Resolved repository reference.", "$ref": "#/components/schemas/AgentToolDataSourceRef" }, "fullName": { "type": [ "null", "string" ], "description": "Owner-qualified repository name." }, "startLine": { "type": "integer", "description": "1-based first returned line.", "format": "int32" }, "endLine": { "type": "integer", "description": "1-based last returned line.", "format": "int32" }, "contentByteSize": { "type": [ "null", "integer" ], "description": "Full file size in bytes when known.", "format": "int64" }, "numberedContent": { "type": [ "null", "string" ], "description": "Returned content prefixed with 1-based line numbers." } }, "additionalProperties": false }, "AgentReadFileToolResponse": { "required": [ "hint" ], "type": "object", "properties": { "found": { "type": "boolean", "description": "Whether the exact requested path resolved." }, "files": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AgentReadFileContent" }, "description": "Resolved file content and line bounds." }, "candidates": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AgentReadFileCandidate" }, "description": "Closest path candidates when exact lookup fails." }, "sameNameCandidates": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AgentReadFileCandidate" }, "description": "Files sharing the requested file name." }, "sameNameTotalCount": { "type": "integer", "description": "Total same-name candidates before truncation.", "format": "int32" }, "hint": { "type": [ "null", "string" ], "description": "Suggested repair or follow-up tool call." }, "error": { "description": "Recoverable read error, when applicable.", "$ref": "#/components/schemas/AgentToolError" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApiWarning" }, "description": "Compatibility warnings, such as accepted deprecated argument aliases." } }, "additionalProperties": false }, "AgentToolDataSourceRef": { "type": "object", "properties": { "type": { "type": [ "null", "string" ], "description": "Repository or Workspace." }, "name": { "type": [ "null", "string" ], "description": "Data-source display name." } }, "additionalProperties": false }, "AgentToolError": { "type": "object", "properties": { "tool": { "type": [ "null", "string" ], "description": "Tool whose request could not be completed." }, "detail": { "type": [ "null", "string" ], "description": "Human-readable explanation of the failure." }, "retry": { "type": [ "null", "string" ], "description": "Whether the caller should repair the request and retry." }, "hint": { "type": [ "null", "string" ], "description": "Concrete guidance for repairing the next request." } }, "additionalProperties": false }, "ArtifactContentDto": { "required": [ "identifier" ], "type": "object", "properties": { "identifier": { "type": [ "null", "string" ], "description": "Requested artifact identifier." }, "found": { "type": "boolean", "description": "Whether the artifact resolved within the caller scope." }, "content": { "type": [ "null", "string" ], "description": "Decrypted artifact content when extractable." }, "contentByteSize": { "type": [ "null", "integer" ], "description": "Artifact content size in bytes.", "format": "int64" }, "startLine": { "type": [ "null", "integer" ], "description": "1-based artifact start line.", "format": "int32" }, "relationships": { "description": "Call counts and bounded caller/callee previews.", "$ref": "#/components/schemas/RelationshipsPreviewDto" } }, "additionalProperties": false }, "ArtifactContentResponse": { "required": [ "artifacts" ], "type": "object", "properties": { "artifacts": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/ArtifactContentDto" }, "description": "One result per requested identifier." }, "hint": { "type": [ "null", "string" ], "description": "Suggested graph-traversal follow-up." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApiWarning" }, "description": "Compatibility warnings, such as accepted deprecated argument aliases." } }, "additionalProperties": false }, "ArtifactDataSourceExtendedDto": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": [ "null", "string" ], "description": "Stable data-source identifier." }, "type": { "description": "Repository or Workspace.", "$ref": "#/components/schemas/ArtifactDataSourceType" }, "name": { "type": [ "null", "string" ], "description": "Display name accepted by data_source selectors." }, "fullName": { "type": [ "null", "string" ], "description": "Owner-qualified repository name; null for workspaces." }, "url": { "type": [ "null", "string" ], "description": "Repository clone URL; null for workspaces." }, "repositoryIds": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Repository ids contained by a workspace." }, "branch": { "type": [ "null", "string" ], "description": "Indexed repository branch." }, "description": { "type": [ "null", "string" ], "description": "User description or generated summary." }, "readiness": { "description": "Current search and chat readiness.", "$ref": "#/components/schemas/DataSourceReadiness" }, "relevanceReason": { "type": [ "null", "string" ], "description": "Why relevance ranking selected this source." } }, "additionalProperties": false }, "ArtifactDataSourceType": { "enum": [ "Repository", "Workspace" ], "type": "string" }, "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": { "description": "ArtifactQuery language version.", "$ref": "#/components/schemas/ArtifactQueryVersionDto" }, "resultShape": { "description": "Rows, Aggregate, or GroupedAggregate.", "$ref": "#/components/schemas/ArtifactQueryResultShapeDto" }, "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 }, "ArtifactQueryResultShapeDto": { "enum": [ "Rows", "Aggregate", "GroupedAggregate" ], "type": "string" }, "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 }, "ArtifactQuerySchemaToolResponse": { "required": [ "dsl_version", "entities", "examples", "fields", "operators", "relationships", "required_limit" ], "type": "object", "properties": { "dsl_version": { "type": [ "null", "string" ], "description": "ArtifactQuery language version." }, "entity": { "type": [ "null", "string" ], "description": "Requested entity filter, when one was supplied." }, "entities": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Queryable entity names." }, "fields": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Queryable field names across the catalog or selected entity." }, "relationships": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Queryable relationship names." }, "operators": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Supported predicate operators." }, "required_limit": { "type": "boolean", "description": "Whether every statement must contain a LIMIT clause." }, "examples": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Valid example statements; empty when include_examples is false." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApiWarning" }, "description": "Compatibility warnings, such as accepted deprecated argument aliases." } }, "additionalProperties": false, "description": "ArtifactQuery v1 catalog used to construct metadata queries." }, "ArtifactQueryVersionDto": { "enum": [ "V1" ], "type": "string" }, "ArtifactRelationshipCountsDto": { "required": [ "ancestors", "descendants", "incomingCalls", "outgoingCalls", "references" ], "type": "object", "properties": { "outgoingCalls": { "type": "integer", "description": "Accessible outgoing-call count.", "format": "int32" }, "incomingCalls": { "type": "integer", "description": "Accessible incoming-call count.", "format": "int32" }, "ancestors": { "type": "integer", "description": "Accessible base-type and ancestor count.", "format": "int32" }, "descendants": { "type": "integer", "description": "Accessible derived-type and implementation count.", "format": "int32" }, "references": { "type": "integer", "description": "Accessible non-call reference count.", "format": "int32" } }, "additionalProperties": false }, "ArtifactRelationshipGroupDto": { "required": [ "items", "relationType", "returnedCount", "totalCount", "truncated" ], "type": "object", "properties": { "relationType": { "description": "Relationship family.", "$ref": "#/components/schemas/ArtifactRelationshipTypeDto" }, "totalCount": { "type": "integer", "description": "Total accessible related artifacts.", "format": "int32" }, "returnedCount": { "type": "integer", "description": "Items returned in this group.", "format": "int32" }, "truncated": { "type": "boolean", "description": "Whether additional items were omitted." }, "items": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/ArtifactRelationshipItemDto" }, "description": "Related artifact previews." } }, "additionalProperties": false }, "ArtifactRelationshipItemDto": { "required": [ "identifier" ], "type": "object", "properties": { "identifier": { "type": [ "null", "string" ], "description": "Stable related artifact identifier." }, "filePath": { "type": [ "null", "string" ], "description": "Repository-relative file path." }, "startLine": { "type": [ "null", "integer" ], "description": "1-based artifact start line.", "format": "int32" }, "shortSummary": { "type": [ "null", "string" ], "description": "AI-generated short summary." } }, "additionalProperties": false }, "ArtifactRelationshipTypeDto": { "enum": [ "OutgoingCalls", "IncomingCalls", "Ancestors", "Descendants", "References" ], "type": "string" }, "ArtifactRelationshipsProfileDto": { "enum": [ "CallsOnly", "InheritanceOnly", "AllRelevant", "ReferencesOnly" ], "type": "string" }, "ArtifactRelationshipsResponse": { "required": [ "found", "profile", "relationships", "sourceIdentifier" ], "type": "object", "properties": { "sourceIdentifier": { "type": [ "null", "string" ], "description": "Requested source artifact identifier." }, "profile": { "description": "Resolved relationship expansion profile.", "$ref": "#/components/schemas/ArtifactRelationshipsProfileDto" }, "found": { "type": "boolean", "description": "Whether the source artifact resolved." }, "relationships": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/ArtifactRelationshipGroupDto" }, "description": "Relationship groups selected by the profile." }, "availableRelationshipCounts": { "description": "Accessible counts for every relationship family.", "$ref": "#/components/schemas/ArtifactRelationshipCountsDto" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApiWarning" }, "description": "Compatibility warnings, such as accepted deprecated argument aliases." } }, "additionalProperties": false }, "ArtifactRelationshipsToolRequest": { "required": [ "identifier" ], "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." }, "identifier": { "type": [ "null", "string" ], "description": "Full artifact identifier from a previous search, fetch, or relationship result." }, "profile": { "enum": [ "calls_only", "inheritance_only", "all_relevant", "references_only" ], "type": [ "null", "string" ], "description": "Relationship profile. Default is calls_only." }, "max_count_per_type": { "type": [ "null", "integer" ], "description": "Maximum relationships to return per relationship type. Default is 50.", "format": "int32" }, "data_source": { "type": [ "null", "string" ], "description": "Optional repository or workspace name/id used to disambiguate the identifier." } }, "additionalProperties": false }, "ChatToolRequest": { "required": [ "question" ], "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." }, "question": { "type": [ "null", "string" ], "description": "Self-contained question. Tool API v3 chat is stateless; include any prior findings, identifiers, constraints, and assumptions." }, "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 }, "ChatToolResponse": { "required": [ "answer", "hint", "stateless" ], "type": "object", "properties": { "answer": { "type": [ "null", "string" ], "description": "Evidence-grounded answer produced by the research agent." }, "stateless": { "type": "boolean", "description": "Always true; Tool API v3 does not retain conversation state." }, "hint": { "type": [ "null", "string" ], "description": "Guidance for carrying context into a subsequent stateless request." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApiWarning" }, "description": "Compatibility warnings, such as accepted deprecated argument aliases." } }, "additionalProperties": false, "description": "Stateless answer returned by the built-in research agent." }, "ConnectionPreviewDto": { "required": [ "identifier" ], "type": "object", "properties": { "identifier": { "type": [ "null", "string" ], "description": "Stable identifier of the connected artifact." }, "summary": { "type": [ "null", "string" ], "description": "AI-generated short summary of the connected artifact." } }, "additionalProperties": false }, "DataSourceDto": { "type": "object", "properties": { "type": { "type": [ "null", "string" ], "description": "Repository or Workspace." }, "id": { "type": [ "null", "string" ], "description": "Stable data-source identifier." }, "name": { "type": [ "null", "string" ], "description": "Data-source display name." } }, "additionalProperties": false }, "DataSourceReadiness": { "enum": [ "NotReady", "PartiallyReady", "Ready" ], "type": "string" }, "FetchArtifactsToolRequest": { "required": [ "identifiers" ], "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." }, "identifiers": { "maxItems": 50, "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Up to 50 artifact identifiers returned by semantic_search, grep_search, read_file, or get_artifact_relationships." }, "data_source": { "type": [ "null", "string" ], "description": "Optional repository or workspace name/id used to disambiguate identifiers." } }, "additionalProperties": false }, "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 }, "GetDataSourcesToolRequest": { "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." }, "query": { "type": [ "null", "string" ], "description": "Optional relevance query used to rank visible data sources." }, "ready_only": { "type": [ "null", "boolean" ], "description": "When true, return only data sources ready for use. Default is true." } }, "additionalProperties": false }, "GetDataSourcesToolResponse": { "required": [ "billed", "data_sources", "hint", "relevance_status", "total_available" ], "type": "object", "properties": { "data_sources": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/ArtifactDataSourceExtendedDto" }, "description": "Visible repositories and workspaces, optionally ranked by relevance." }, "relevance_status": { "type": [ "null", "string" ], "description": "Outcome of optional relevance ranking: not_requested, skipped, failed_open, or succeeded." }, "total_available": { "type": "integer", "description": "Number of visible data sources before relevance filtering.", "format": "int32" }, "billed": { "type": "boolean", "description": "Whether this request consumed billed relevance-ranking usage." }, "hint": { "type": [ "null", "string" ], "description": "Guidance for selecting data sources in subsequent tool calls." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApiWarning" }, "description": "Compatibility warnings, such as accepted deprecated argument aliases." } }, "additionalProperties": false, "description": "Result of listing data sources visible to the caller." }, "GrepSearchMatchDto": { "type": "object", "properties": { "lineNumber": { "type": "integer", "description": "1-based line number.", "format": "int32" }, "startColumn": { "type": "integer", "description": "1-based inclusive start column.", "format": "int32" }, "endColumn": { "type": "integer", "description": "1-based inclusive end column.", "format": "int32" }, "lineText": { "type": [ "null", "string" ], "description": "Source line containing the match." }, "remark": { "type": [ "null", "string" ], "description": "Preview limitation or truncation note." }, "contextLines": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/GrepSearchPreviewLineDto" }, "description": "Previous, matching, and next preview lines when available." } }, "additionalProperties": false }, "GrepSearchPreviewLineDto": { "type": "object", "properties": { "lineNumber": { "type": "integer", "description": "1-based source line number.", "format": "int32" }, "lineText": { "type": [ "null", "string" ], "description": "Capped source-line preview." } }, "additionalProperties": false }, "GrepSearchResponse": { "type": "object", "properties": { "results": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/GrepSearchResultDto" }, "description": "Artifacts containing literal or regular-expression matches." }, "pathFilter": { "description": "Path-filter interpretation and rejection diagnostics.", "$ref": "#/components/schemas/PathFilterDiagnostic" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApiWarning" }, "description": "Compatibility warnings, such as accepted deprecated argument aliases." } }, "additionalProperties": false }, "GrepSearchResultDto": { "type": "object", "properties": { "kind": { "type": [ "null", "string" ], "description": "Matched artifact kind." }, "dataSource": { "description": "Repository or workspace containing the match.", "$ref": "#/components/schemas/DataSourceDto" }, "identifier": { "type": [ "null", "string" ], "description": "Stable identifier accepted by fetch and relationship tools." }, "location": { "description": "Primary file location; line is 1-based and character is 0-based.", "$ref": "#/components/schemas/LocationDto" }, "startLine": { "type": [ "null", "integer" ], "description": "1-based artifact start line when indexed.", "format": "int32" }, "endLine": { "type": [ "null", "integer" ], "description": "1-based artifact end line when indexed.", "format": "int32" }, "score": { "type": "number", "description": "Search relevance score.", "format": "double" }, "contentByteSize": { "type": [ "null", "integer" ], "description": "Artifact content size in bytes when known.", "format": "int64" }, "matchCount": { "type": "integer", "description": "Total matches found in this artifact.", "format": "int32" }, "matches": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/GrepSearchMatchDto" }, "description": "Bounded preview of individual matches." }, "matchedByName": { "type": [ "null", "boolean" ], "description": "True when only the file name or path matched." }, "summary": { "type": [ "null", "string" ], "description": "AI-generated short artifact summary." } }, "additionalProperties": false }, "GrepSearchToolRequest": { "required": [ "query" ], "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." }, "query": { "type": [ "null", "string" ], "description": "Literal string or regex pattern to search for." }, "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." }, "paths": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Optional repository-relative path prefixes to include." }, "extensions": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Optional file extensions to include, for example cs, ts, or py." }, "max_results": { "type": [ "null", "integer" ], "description": "Optional maximum number of search results.", "format": "int32" }, "exclude_markdown": { "type": [ "null", "boolean" ], "description": "Exclude Markdown files from search results. Default is false." }, "regex": { "type": [ "null", "boolean" ], "description": "Set true to treat query as a regular expression. Default is false." } }, "additionalProperties": false }, "LocationDto": { "type": "object", "properties": { "path": { "type": [ "null", "string" ], "description": "Repository-relative file path." }, "range": { "description": "Source range within the file.", "$ref": "#/components/schemas/RangeDto" } }, "additionalProperties": false }, "PathFilterDiagnostic": { "type": "object", "properties": { "interpreted": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/PatternInterpretation" }, "description": "Accepted path patterns and their interpretation." }, "rejected": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/PathFilterRejection" }, "description": "Rejected path patterns with repair recommendations." }, "matchAll": { "type": "boolean", "description": "Whether the path scope matches every file." }, "scopeHasMatches": { "type": [ "null", "boolean" ], "description": "Whether any indexed files match the path scope." }, "status": { "description": "Path-filter evaluation status.", "$ref": "#/components/schemas/PathFilterStatus" } }, "additionalProperties": false }, "PathFilterRejection": { "type": "object", "properties": { "input": { "type": [ "null", "string" ], "description": "Original rejected path-filter pattern." }, "reason": { "description": "Why the pattern could not be applied.", "$ref": "#/components/schemas/PathSpecRejectionReason" }, "recommendation": { "type": [ "null", "string" ], "description": "Suggested replacement or correction." } }, "additionalProperties": false }, "PathFilterStatus": { "enum": [ "NoPaths", "ScopeMatchedZeroFiles", "ScopeMatchedNoContent", "AllPathsRejected" ], "type": "string" }, "PathPatternClass": { "enum": [ "PlainPath", "BareToken", "BasenameOnly", "SimpleGlob", "PosixGlob", "Regex", "Substring" ], "type": "string" }, "PathPatternTier": { "enum": [ "PlainPath", "Wildcard", "Regex", "PostFilter" ], "type": "string" }, "PathSpecRejectionReason": { "enum": [ "EmptyAfterTrim", "NegationOnlyNoBody", "PatternTooLong", "PatternExpansionTooLarge", "PcreFeatureUnsupported", "RegexSyntaxUnsupported", "RegexNoLiteral", "NoSafeLiteral", "EmbeddedAnchor", "TotalFanoutExceeded" ], "type": "string" }, "PatternInterpretation": { "type": "object", "properties": { "input": { "type": [ "null", "string" ], "description": "Original path-filter pattern." }, "class": { "description": "Detected pattern class, such as exact path, prefix, or glob.", "$ref": "#/components/schemas/PathPatternClass" }, "tier": { "description": "Matching tier selected for the pattern.", "$ref": "#/components/schemas/PathPatternTier" }, "isNegation": { "type": "boolean", "description": "Whether the pattern excludes matching paths." } }, "additionalProperties": false }, "PositionDto": { "type": "object", "properties": { "line": { "type": "integer", "description": "1-based source line.", "format": "int32" }, "character": { "type": "integer", "description": "0-based character offset.", "format": "int32" } }, "additionalProperties": false }, "RangeDto": { "type": "object", "properties": { "start": { "description": "Range start position.", "$ref": "#/components/schemas/PositionDto" }, "end": { "description": "Range end position.", "$ref": "#/components/schemas/PositionDto" } }, "additionalProperties": false }, "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 }, "RelationshipsPreviewDto": { "type": "object", "properties": { "outgoingCallsCount": { "type": [ "null", "integer" ], "description": "Total accessible outgoing calls.", "format": "int32" }, "outgoingCalls": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/ConnectionPreviewDto" }, "description": "Bounded preview of called artifacts." }, "incomingCallsCount": { "type": [ "null", "integer" ], "description": "Total accessible incoming calls.", "format": "int32" }, "incomingCalls": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/ConnectionPreviewDto" }, "description": "Bounded preview of calling artifacts." } }, "additionalProperties": false }, "RepositoryOntologyToolResponse": { "required": [ "content", "repository_count" ], "type": "object", "properties": { "repository_count": { "type": "integer", "description": "Number of repositories represented by this response. Always one in Tool API v3.", "format": "int32" }, "content": { "type": [ "null", "string" ], "description": "Repository ontology formatted as Markdown." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApiWarning" }, "description": "Compatibility warnings, such as accepted deprecated argument aliases." } }, "additionalProperties": false, "description": "Generated high-level map of one repository." }, "RepositoryToolRequest": { "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." } }, "additionalProperties": false }, "SearchResponse": { "type": "object", "properties": { "results": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/SearchResultDto" }, "description": "Ranked semantic-search results." }, "pathFilter": { "description": "Path-filter interpretation and rejection diagnostics.", "$ref": "#/components/schemas/PathFilterDiagnostic" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApiWarning" }, "description": "Compatibility warnings, such as accepted deprecated argument aliases." } }, "additionalProperties": false }, "SearchResultDto": { "type": "object", "properties": { "kind": { "type": [ "null", "string" ], "description": "Artifact kind, such as method, class, or file." }, "dataSource": { "description": "Repository or workspace containing the artifact.", "$ref": "#/components/schemas/DataSourceDto" }, "identifier": { "type": [ "null", "string" ], "description": "Stable identifier accepted by fetch and relationship tools." }, "location": { "description": "Repository-relative path and source range.", "$ref": "#/components/schemas/LocationDto" }, "score": { "type": "number", "description": "Search relevance score from 0 to 1.", "format": "double" }, "description": { "type": [ "null", "string" ], "description": "AI-generated artifact description." }, "contentByteSize": { "type": [ "null", "integer" ], "description": "Artifact content size in bytes when known.", "format": "int64" }, "snippet": { "type": [ "null", "string" ], "description": "Short matching code snippet when available." }, "content": { "type": [ "null", "string" ], "description": "Full artifact content when explicitly requested." } }, "additionalProperties": false }, "SemanticSearchToolRequest": { "required": [ "question" ], "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." }, "question": { "type": [ "null", "string" ], "description": "Natural-language search question." }, "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." }, "paths": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Optional repository-relative path prefixes to include." }, "extensions": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Optional file extensions to include, for example cs, ts, or py." }, "max_results": { "type": [ "null", "integer" ], "description": "Optional maximum number of search results.", "format": "int32" }, "exclude_markdown": { "type": [ "null", "boolean" ], "description": "Exclude Markdown files from search results. Default is false." } }, "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 }, "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 }, "ToolApiRepairableResult": { "required": [ "error" ], "type": "object", "properties": { "error": { "description": "Structured error details used to repair the request and retry.", "$ref": "#/components/schemas/ToolApiRepairableError" }, "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." }, "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 } }, "securitySchemes": { "ApiKeyScheme": { "type": "http", "description": "API Key authentication using Bearer token. Example: \"Authorization: Bearer {apiKey}\"", "scheme": "bearer", "bearerFormat": "API Key" } } }, "security": [ { "ApiKeyScheme": [] } ], "tags": [ { "name": "ToolApi", "description": "CodeAlive Tool API v3" } ] }