{ "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": { "$ref": "#/components/schemas/ToolApiEnvelope" }, "example": { "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." } }, "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": { "$ref": "#/components/schemas/ToolApiEnvelope" }, "example": { "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." } }, "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": { "$ref": "#/components/schemas/ToolApiEnvelope" }, "example": { "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" }, "score": 1, "matchCount": 2, "matches": [ { "lineNumber": 42, "startColumn": 7, "endColumn": 19, "lineText": "class TaskExecutor:", "contextLines": [] } ] } ] }, "rendered": "\n \n\nFetch relevant identifiers with fetch_artifacts or read local files before drawing conclusions." } }, "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" }, "score": 1, "matchCount": 2, "matches": [ { "lineNumber": 42, "startColumn": 7, "endColumn": 19, "lineText": "class TaskExecutor:", "contextLines": [] } ] } ] }, "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": { "$ref": "#/components/schemas/ToolApiEnvelope" }, "example": { "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" } }, "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": { "$ref": "#/components/schemas/ToolApiEnvelope" }, "example": { "obj": { "trees": [ { "dataSource": { "type": "Repository", "name": "agent-framework" }, "fullName": "CodeAlive-AI/agent-framework", "path": ".", "found": true, "tree": "src/ — core packages\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.\"}" } }, "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": { "$ref": "#/components/schemas/ToolApiEnvelope" }, "example": { "obj": { "found": true, "files": [ { "identifier": "CodeAlive-AI/agent-framework::README.md", "path": "README.md", "dataSource": { "type": "Repository", "name": "agent-framework" }, "fullName": "CodeAlive-AI/agent-framework", "startLine": 1, "endLine": 2, "contentByteSize": 96, "numberedContent": "1: # Agent Framework\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.\"}" } }, "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": { "$ref": "#/components/schemas/ToolApiEnvelope" }, "example": { "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.\"}" } }, "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": { "$ref": "#/components/schemas/ToolApiEnvelope" }, "example": { "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}]}]}" } }, "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": { "$ref": "#/components/schemas/ToolApiEnvelope" }, "example": { "obj": { "dsl_version": "artifactquery/v1", "entity": "files", "entities": [ "files", "symbols", "functions" ], "fields": [ "path", "language", "lines", "complexity" ], "relationships": [ "outgoing_calls", "incoming_calls", "references" ], "operators": [ "=", "!=", ">", ">=", "<", "<=", "IN" ], "required_limit": true, "examples": [ "SELECT path, language, lines FROM files LIMIT 20", "SELECT count() AS count, language FROM files GROUP BY language LIMIT 20" ] }, "rendered": "{\"dsl_version\":\"artifactquery/v1\",\"entities\":[\"files\",\"symbols\",\"functions\"],\"required_limit\":true,\"examples\":[\"SELECT path, language, lines FROM files LIMIT 20\"]}" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ToolApiEnvelope" } } } }, "400": { "description": "Bad request, including malformed JSON, unknown output_format, or invalid transport-level input." }, "401": { "description": "Authentication failed or API key is missing." }, "403": { "description": "The caller is not authorized for the requested data source or plan feature." }, "429": { "description": "Rate limit, quota, or plan limit exceeded." }, "500": { "description": "Unexpected server failure." } }, "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": { "$ref": "#/components/schemas/ToolApiEnvelope" }, "example": { "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}" } }, "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": { "$ref": "#/components/schemas/ToolApiEnvelope" }, "example": { "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` …" } }, "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": { "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 }, "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 }, "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 }, "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 }, "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 }, "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 }, "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 }, "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 } }, "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" } ] }