# Apira API

> Semantic search for GitHub repositories. Built for AI agents.

## Authentication

All search endpoints require an API key passed via the `X-API-Key` header.
Get your API key at: https://apira.dev/dashboard

## Endpoints

### Search GitHub Repositories
POST /v1/github/search

Search across 56,000+ indexed GitHub repositories using Pinecone vector semantic matching, with an optional cross-encoder rerank stage (Voyage `rerank-2.5-lite`) that reorders the top 100 ranked candidates when enabled. When the rerank stage ran, the response includes `meta.reranked` (true if it reordered, false if it fell back on error) and `meta.rerankMs`.

**Required fields:**
- `query` (string): Natural language search query (max 500 chars)

**Optional fields:**
- `limit` (number): Number of results, 1-50 (default: 10)
- `filters` (object): Pinecone metadata filters applied before ranking (see below)

**Available filters:**
- `minStars` (number): Minimum GitHub star count. e.g. `{ minStars: 1000 }`
- `maxStars` (number): Maximum GitHub star count. e.g. `{ maxStars: 5000 }`. Combine with minStars for star ranges: `{ minStars: 100, maxStars: 5000 }`
- `language` (string): Programming language (case-insensitive). GitHub Title Case (e.g. "Python", "JavaScript") or lowercase both work. e.g. `{ language: "python" }`
- `excludeRepos` (string[]): Repos to exclude, max 50. Format: "owner/repo". e.g. `{ excludeRepos: ["pallets/flask", "django/django"] }`
- `minForks` (number): Minimum fork count. e.g. `{ minForks: 100 }`
- `maxForks` (number): Maximum fork count. e.g. `{ maxForks: 500 }`
- `categories` (string[]): Filter by Apira's 13-category taxonomy (assigned by LLM classifier). Omit for the default production allowlist, which excludes classified `educational` and `curated-list` repos. Pass `categories: ["educational"]` or `categories: ["curated-list"]` to search those types explicitly. Pass `categories: []` to remove category filtering and include all categories.
- `topics` (string[]): Filter by GitHub tags set by repo owners (freeform). Must match at least one topic. e.g. `{ topics: ["kubernetes", "docker"] }`
- `excludeArchived` (boolean): Exclude GitHub-archived repos from results. Default: `true`. Pass `false` when you specifically want historical or legacy options.
- `staleAfterMonths` (positive integer): Exclude repos not pushed within the last N months. No server default — choose per query intent (for example, 18 for production-ready libraries, 6-12 for bleeding-edge, 36-60 for legacy surveys).

**Available categories (Apira taxonomy, 13 fixed values):**
- `library`: Reusable packages (npm, pip, gems, crates)
- `framework`: Opinionated scaffolding (Django, Rails, Express)
- `tool`: CLIs, dev tools, build tools, linters
- `application`: Complete runnable apps (servers, desktop, mobile)
- `infrastructure`: Cloud, orchestration, CI/CD, monitoring
- `ai-ml`: ML libraries, model training, data science
- `agent`: LLM agents, autonomous systems, AI orchestration
- `frontend`: UI libraries, component systems, CSS frameworks
- `data`: Databases, ORMs, data pipelines, ETL
- `starter`: Project templates, boilerplates, scaffolding
- `curated-list`: Awesome-lists, resource collections (excluded by default)
- `educational`: Tutorials, courses, learning resources (excluded by default)
- `plugin`: Extensions, addons for a specific platform

**Query construction tips:**
- Be specific in `query` — use technical terms, not vague descriptions
- Combine filters to narrow results: `{ language: "python", minStars: 100, categories: ["library"] }`
- Use `excludeRepos` to remove repos you have already evaluated
- Use `categories` to remove category noise: e.g. `["library"]`, `["framework"]`, `["tool"]`, `["agent"]`, or `["infrastructure"]`
- Use `topics` to filter by GitHub tags set by repo owners (e.g. `["kubernetes", "docker"]`)
- Read `meta.appliedFilters` to see the effective defaults and filters applied to the search
- Use `minForks`/`maxForks` to filter by community activity

**Example request:**
```
curl -X POST https://api.apira.dev/v1/github/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: apira_your_key_here" \
  -d '{
    "query": "OAuth token metering middleware",
    "limit": 5,
    "filters": { "categories": ["library", "tool"], "excludeArchived": true }
  }'
```

**Example response:**
```json
{
  "query": "OAuth token metering middleware",
  "results": [
    {
      "url": "https://github.com/acme/oauth-meter",
      "name": "acme/oauth-meter",
      "description": "OAuth2 token metering middleware",
      "score": 0.89,
      "language": "Go",
      "stars": 1240,
      "forks": 89,
      "topics": ["oauth", "middleware", "metering"],
      "pushedAt": "2026-03-15T10:30:00.000Z",
      "llmsUrl": "https://raw.githubusercontent.com/acme/oauth-meter/main/llms.txt",
      "evidence": ["Implements OAuth2 token metering with per-user budgets..."]
    }
  ],
  "meta": {
    "total": 5,
    "timeMs": 180,
    "appliedFilters": {
      "categories": { "mode": "explicit", "values": ["library", "tool"], "includeUncategorized": true },
      "excludeArchived": true,
      "minStars": null,
      "maxStars": null,
      "minForks": null,
      "maxForks": null,
      "language": null,
      "excludeRepos": [],
      "topics": [],
      "staleAfterMonths": null
    },
    "reranked": true,
    "rerankMs": 420
  }
}
```

Note: `meta.appliedFilters.categories.mode` is `default` when categories are omitted, `explicit` when one or more categories are supplied, and `all` when `categories: []` disables category filtering. `meta.appliedFilters.categories.includeUncategorized` reports whether repos without classified category metadata pass the effective category filter. `meta.reranked` and `meta.rerankMs` in the example above only appear when the rerank stage actually ran. They are absent when rerank is disabled server-side, when the ranked candidate pool is empty, or when the query is whitespace-only.

**Intent-based examples:**
- Production-ready libraries/tools: `{ "query": "OAuth token metering middleware", "limit": 10, "filters": { "categories": ["library", "tool"], "minStars": 100, "staleAfterMonths": 18 } }`
- Active non-archived repos: `{ "query": "Kubernetes cost monitoring", "limit": 10, "filters": { "excludeArchived": true, "staleAfterMonths": 12 } }`
- Educational/tutorial search: `{ "query": "learn compiler construction tutorial", "limit": 10, "filters": { "categories": ["educational"] } }`
- Broad discovery: `{ "query": "LLM agent orchestration", "limit": 10, "filters": { "categories": [] } }`
- Iterative search: `{ "query": "TypeScript ORM query builder", "limit": 10, "filters": { "excludeRepos": ["prisma/prisma"] } }`

### Health Check
GET /health

Returns API health status. No authentication required.

## Rate Limits
<!-- Keep in sync with DEFAULT_RATE_LIMITS in config/defaults.ts -->

- 60 requests/minute per API key
- 30 requests/minute per IP (unauthenticated)
- On 429: wait for the number of seconds in the `Retry-After` header before retrying

## Pricing

- $0.001 per search request
- Top up any amount from $5 to $1,000 at: https://apira.dev/dashboard

## Full API Spec

Machine-readable OpenAPI 3.1 spec: /.well-known/openapi.json