{ "openapi": "3.1.0", "info": { "title": "Optiq Code API", "version": "1.0.0", "description": "Deterministic code context engine for AI agents. Index repositories, search code with natural language, resolve symbol relationships, and retrieve ranked results with confidence scores.", "contact": { "name": "Optiq Code Support", "email": "hello@optiqcode.com", "url": "https://optiqcode.com/contact" }, "license": { "name": "Proprietary", "url": "https://optiqcode.com/terms" }, "x-logo": { "url": "https://optiqcode.com/favicon-96x96.png" } }, "servers": [ { "url": "https://api.optiqcode.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/search": { "post": { "operationId": "searchCode", "summary": "Search indexed code", "description": "Search indexed codebases with natural language or structured filters. Returns ranked results with function signatures, symbol context, and confidence scores.", "tags": ["Search"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "example": { "query": "authentication middleware", "repo_id": "my-project", "limit": 10 } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/repos": { "get": { "operationId": "listRepos", "summary": "List indexed repositories", "description": "Returns all repositories indexed under the authenticated account.", "tags": ["Repositories"], "responses": { "200": { "description": "List of repositories", "content": { "application/json": { "schema": { "type": "object", "properties": { "repos": { "type": "array", "items": { "$ref": "#/components/schemas/Repository" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "indexRepo", "summary": "Index a repository", "description": "Start indexing a repository. Parses ASTs, resolves imports, and builds dependency graphs across 12 supported languages.", "tags": ["Repositories"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexRequest" }, "example": { "repo_url": "https://github.com/user/repo" } } } }, "responses": { "202": { "description": "Indexing started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/repos/{repo_id}": { "get": { "operationId": "getRepo", "summary": "Get repository details", "description": "Returns details and indexing status for a specific repository.", "tags": ["Repositories"], "parameters": [ { "name": "repo_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Repository identifier" } ], "responses": { "200": { "description": "Repository details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Repository" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteRepo", "summary": "Delete a repository", "description": "Remove a repository and all its indexed data.", "tags": ["Repositories"], "parameters": [ { "name": "repo_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Repository identifier" } ], "responses": { "204": { "description": "Repository deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/jobs/{job_id}": { "get": { "operationId": "getJobStatus", "summary": "Check indexing job status", "description": "Poll the status of an indexing job.", "tags": ["Jobs"], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job ID from indexing request" } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/health": { "get": { "operationId": "healthCheck", "summary": "Health check", "description": "Returns API health status. No authentication required.", "tags": ["System"], "security": [], "responses": { "200": { "description": "API is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "version": { "type": "string", "example": "1.0.0" } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "API key from https://optiqcode.com/dashboard/api-keys" } }, "schemas": { "SearchRequest": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "description": "Natural language search query or structured filter (e.g., 'symbol:handleAuth', 'file:middleware type:function')" }, "repo_id": { "type": "string", "description": "Repository identifier to search within" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Maximum number of results" }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Pagination offset" }, "intent": { "type": "string", "enum": ["navigate", "understand", "debug", "refactor"], "description": "Search intent hint for ranking" } } }, "SearchResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "total": { "type": "integer", "description": "Total matching results" }, "query_time_ms": { "type": "number", "description": "Query execution time in milliseconds" } } }, "SearchResult": { "type": "object", "properties": { "file_path": { "type": "string", "description": "Relative file path" }, "line_start": { "type": "integer", "description": "Starting line number" }, "line_end": { "type": "integer", "description": "Ending line number" }, "content": { "type": "string", "description": "Matched code content" }, "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Relevance confidence score" }, "symbol": { "type": "string", "description": "Symbol name if applicable" }, "symbol_type": { "type": "string", "enum": ["function", "class", "method", "variable", "import", "type"], "description": "Type of symbol" }, "language": { "type": "string", "description": "Programming language" } } }, "IndexRequest": { "type": "object", "required": ["repo_url"], "properties": { "repo_url": { "type": "string", "format": "uri", "description": "Git repository URL" }, "branch": { "type": "string", "description": "Branch to index (default: default branch)" }, "fresh": { "type": "boolean", "default": false, "description": "Force re-index from scratch" } } }, "IndexResponse": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Job ID for polling status" }, "repo_id": { "type": "string", "description": "Repository identifier" }, "status": { "type": "string", "enum": ["queued", "indexing"], "description": "Initial job status" } } }, "Repository": { "type": "object", "properties": { "repo_id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": ["indexing", "ready", "error", "stale"] }, "languages": { "type": "array", "items": { "type": "string" } }, "files_indexed": { "type": "integer" }, "lines_indexed": { "type": "integer" }, "last_indexed": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "JobStatus": { "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "indexing", "completed", "failed"] }, "progress": { "type": "number", "minimum": 0, "maximum": 100, "description": "Completion percentage" }, "files_processed": { "type": "integer" }, "files_total": { "type": "integer" }, "error": { "type": "string", "description": "Error message if failed" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "hint": { "type": "string", "description": "Suggested resolution" } } } } } }, "responses": { "BadRequest": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Missing required field: query", "hint": "Include a 'query' string in the request body" } } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing API key", "hint": "Get an API key at https://optiqcode.com/dashboard/api-keys" } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Repository not found", "hint": "Check the repo_id and ensure it has been indexed" } } } } }, "RateLimited": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until rate limit resets" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded", "hint": "Wait for the Retry-After period or upgrade your plan" } } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred", "hint": "Check https://optiqcode.com/status for service health" } } } } } } }, "tags": [ { "name": "Search", "description": "Code search operations" }, { "name": "Repositories", "description": "Repository management" }, { "name": "Jobs", "description": "Indexing job tracking" }, { "name": "System", "description": "Health and status" } ], "externalDocs": { "description": "Optiq Code Documentation", "url": "https://optiqcode.com/docs" } }