# Perivis AI API

## Overview
This API provides financial data search and analysis functionality for Perivis agents.

## Endpoints

- `GET /` - API information (JSON)
- `GET /health` - Health check
- `GET /info` - This documentation (Markdown)
- `GET /api/status` - Service status
- `GET /api/skills` - List available API capabilities
- `GET /api/issuers/search` - Search for companies/issuers by name
- `GET /api/glints/find` - Find social posts for a stock ticker
- `GET /api/notes/find` - Find research notes for a stock ticker
- `GET /api/note/<public_url_id>` - Get full content of a specific note

## MCP Server (Model Context Protocol)

For AI agent integration, the API also provides a full MCP server implementation at `/mcp`:

- `GET /mcp/server/info` - MCP server metadata and capabilities
- `GET /mcp/tools/list` - List all available MCP tools
- `POST /mcp/tools/call` - Invoke an MCP tool

See [MCP_IMPLEMENTATION.md](MCP_IMPLEMENTATION.md) for detailed documentation.

## Main Features

### 1. Issuer Search
Search for companies by name with fuzzy matching. Returns matching issuers with their stock identifiers (BSE, NSE, US).

**Endpoint:** `GET /api/issuers/search`

**Parameters:**
- `q` (required) - Company name to search for
- `limit` (optional, default: 10) - Maximum number of results

**Example:**
```bash
curl "https://perivis.ai/api/issuers/search?q=Reliance&limit=5"
```

### 2. Glints (Social Posts)
Find social posts (glints) for a given stock ticker. Returns recent posts tagged with the corresponding issuer.

**Endpoint:** `GET /api/glints/find`

**Parameters:**
- `identifier` (required) - Stock identifier in format CODE.EXCHANGE (e.g., "500325.BSE", "RELIANCE.NSE", "AAPL.US")

**Example:**
```bash
curl "https://perivis.ai/api/glints/find?identifier=RELIANCE.NSE"
```

### 3. Research Notes
Find research notes and summaries for a stock ticker. For US stocks, returns 8-K summaries. For Indian stocks, returns quarterly results, corporate announcements, and earnings call summaries.

**Endpoint:** `GET /api/notes/find`

**Parameters:**
- `ticker` (required) - Stock ticker in format CODE.EXCHANGE (e.g., "RELIANCE.NSE", "AAPL.US", "500325.BSE")

**Example:**
```bash
curl "https://perivis.ai/api/notes/find?ticker=RELIANCE.NSE"
```

### 4. Skills Discovery
Get a machine-readable list of all available API capabilities with parameter specifications.

**Endpoint:** `GET /api/skills`

**Example:**
```bash
curl "https://perivis.ai/api/skills"
```

## Supported Stock Exchanges
- **BSE** (Bombay Stock Exchange) - Indian stocks
- **NSE** (National Stock Exchange of India) - Indian stocks
- **US** - United States stocks