# Optiq Code

> A context engine for software repositories. Optiq indexes your codebase, resolves symbol relationships, and delivers ranked search results that AI coding agents can trust.

## What Optiq Does

Optiq Code is a deterministic context retrieval engine. It parses source code into ASTs, builds dependency graphs, and creates hybrid search indexes (semantic + keyword). When an AI agent needs to find relevant code, Optiq returns ranked results with function signatures, call graphs, and confidence scores — in ~1-2 seconds.

## Key Features

- **Hybrid Search**: Semantic vector search + keyword matching in a single query
- **AST Parsing**: Full abstract syntax tree analysis for 12 languages (Python, TypeScript, JavaScript, TSX, Rust, Go, Java, C, C++, Ruby, PHP, C#)
- **Symbol Resolution**: Tracks imports, exports, function calls, and references across files
- **Confidence Scoring**: Every result includes a relevance score so agents can filter by quality
- **MCP Server**: Built-in Model Context Protocol server for direct agent integration
- **CLI Tool**: `npm install -g @optiqcode/cli` — index, search, and serve from the terminal

## When to Use Optiq

Use Optiq when your AI coding agent needs to:
- Find the right function in a large codebase without scanning every file
- Understand how code connects across modules (who calls what, who imports what)
- Get precise context windows instead of dumping entire files into the prompt
- Reduce hallucination by providing verified, ranked code context

## API Overview

Base URL: `https://api.optiqcode.com`
Authentication: Bearer token (API key from dashboard)

### Endpoints

- `POST /api/v1/search` — Search indexed code with natural language or structured filters
- `POST /api/v1/repos` — Add a repository for indexing
- `GET /api/v1/repos` — List all indexed repositories
- `DELETE /api/v1/repos/{repo_id}` — Delete a repository and its index
- `POST /api/v1/repos/{repo_id}/reindex` — Trigger a fresh reindex
- `GET /api/v1/usage` — Get usage logs
- `GET /api/v1/usage/summary` — Get usage summary stats
- `GET /api/v1/usage/daily` — Get daily query counts
- `GET /api/v1/keys` — List API keys
- `POST /api/v1/keys` — Create a new API key
- `DELETE /api/v1/keys/{key_id}` — Revoke an API key
- `GET /api/v1/status/health` — Health check

### Search Request

```json
POST /api/v1/search
Authorization: Bearer oq_...
Content-Type: application/json

{
  "query": "authentication middleware that validates JWT tokens",
  "repo_id": "my-project",
  "limit": 10,
  "include_graph": true
}
```

### Search Response

```json
{
  "results": [
    {
      "file_path": "src/middleware/auth.ts",
      "symbol": "validateToken",
      "type": "function",
      "score": 0.97,
      "line_start": 24,
      "line_end": 42,
      "snippet": "export async function validateToken(token: string, secret: JWKSet): Promise<DecodedToken | null>",
      "references": 6,
      "callers": ["checkSession", "authGuard"]
    }
  ],
  "total": 5,
  "latency_ms": 416
}
```

## Installation

```bash
npm install -g @optiqcode/cli
optiq login
optiq index .
optiq search "your query"
optiq mcp  # Start MCP server for agent integration
```

## MCP Integration

Optiq includes a built-in MCP (Model Context Protocol) server. Start it with `optiq mcp` and connect from any MCP-compatible agent (Cursor, Cline, Windsurf, Claude, etc).

Available MCP tools:
- `optiq_search` — Search indexed code
- `optiq_index` — Index a directory
- `optiq_repos` — List indexed repositories
- `optiq_status` — Check indexing job status

## Pricing

- **Free**: 3 repos, 50k lines indexed, 100 queries/day, MCP server + CLI
- **Pro (Free during beta)**: Unlimited everything, bring your own Voyage + Groq API keys
- **Enterprise**: Custom deployment, SSO/SAML, audit logging, dedicated support — [contact sales](https://optiqcode.com/contact)

## Security

- AES-256-GCM encryption at rest
- TLS 1.3 in transit
- Per-user database isolation
- Role-based access controls with MFA
- SOC 2 Type II certification in progress
- Full details: [Security](https://optiqcode.com/security)

## Links

- [Documentation](https://optiqcode.com/docs)
- [Developer Portal](https://optiqcode.com/developers)
- [Pricing](https://optiqcode.com/pricing)
- [Blog](https://optiqcode.com/blog)
- [Security](https://optiqcode.com/security)
- [Status](https://optiqcode.com/status)
- [Compare](https://optiqcode.com/compare)
- [NPM Package](https://www.npmjs.com/package/@optiqcode/cli)
- [GitHub](https://github.com/optiqcode)
- [Contact](https://optiqcode.com/contact)
- [About](https://optiqcode.com/about)
- [Privacy Policy](https://optiqcode.com/privacy)
- [Terms of Service](https://optiqcode.com/terms)

## Machine-Readable Discovery

- [OpenAPI Spec](https://optiqcode.com/openapi.json) — Full API specification (OpenAPI 3.1)
- [MCP Server](https://optiqcode.com/.well-known/mcp) — Model Context Protocol discovery
- [Agent Card](https://optiqcode.com/.well-known/agent-card.json) — Agent capabilities and auth
- [AI Plugin](https://optiqcode.com/.well-known/ai-plugin.json) — OpenAI plugin manifest
- [OAuth Metadata](https://optiqcode.com/.well-known/oauth-authorization-server) — Authorization server metadata
- [Pricing (markdown)](https://optiqcode.com/pricing.md) — Machine-readable pricing
- [Agent Mode](https://optiqcode.com/?mode=agent) — Structured JSON view for agents

## Error Handling

All errors return structured JSON:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: query",
    "hint": "Include a 'query' string in the request body"
  }
}
```

HTTP status codes: 400 (bad request), 401 (unauthorized), 403 (forbidden scope), 404 (not found), 429 (rate limited), 500 (server error).

## Rate Limits

Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After` (on 429).

- Free: 100 queries/day, 10 index ops/day
- Pro: Unlimited (1min sliding window)
- Enterprise: Custom

## Streaming

Add `Accept: text/event-stream` for SSE progress updates during indexing and streaming search results.

## Authentication for Agents

1. Get an API key at https://optiqcode.com/dashboard/api-keys (self-serve, no credit card)
2. Pass as Bearer token: `Authorization: Bearer sk-your-key`
3. Keys support scoped permissions: `search:read`, `repos:read`, `repos:write`, `repos:delete`, `jobs:read`
4. OAuth discovery: https://optiqcode.com/.well-known/oauth-authorization-server