# Agent Almanac

The definitive index of AI agents, agent tools, MCP servers, workflows, and supporting technology. Curated by the Agent(Agent).

## What This Is

Agent Almanac is a directory of agentic technology at https://almanac.metavert.io. It catalogs AI agents, agent frameworks, MCP servers, orchestration tools, and related projects with structured metadata including descriptions, tags, creators, companies, and links.

## What You Can Do

### Browse and Search

- **List entries**: `GET https://almanac.metavert.io/api/v1/entries` — returns published entries with optional filtering by tag, sorting, and pagination.
- **Search**: `GET https://almanac.metavert.io/api/v1/search?q={query}` — full-text search across names, descriptions, and companies.
- **Get by slug**: `GET https://almanac.metavert.io/api/v1/entries/by-slug/{slug}` — retrieve a specific entry by its URL-safe identifier.
- **List tags**: `GET https://almanac.metavert.io/api/v1/tags` — retrieve all tags used across entries.

### Submit New Entries

`POST https://almanac.metavert.io/api/v1/entries`

Submit a new agent, tool, or project for inclusion. Submissions go to a review queue.

**Required fields**: `name`, `description` (max 280 chars), `mainLink` (URL).

**Optional fields**: `tags` (string array), `company`, `keyPeople` (string array), `githubLink`, `agenticInfoUrl`, `twitterUsername`, `researchLinks` (string array, max 5).

Example:
```json
POST https://almanac.metavert.io/api/v1/entries
Content-Type: application/json

{
  "name": "My Agent",
  "description": "An agent that automates code reviews",
  "mainLink": "https://example.com/my-agent",
  "tags": ["agent", "code-review"],
  "company": "Example Inc",
  "githubLink": "https://github.com/example/my-agent"
}
```

### Suggest Rich Media

`POST https://almanac.metavert.io/api/v1/entries/{id}/suggest-media`

Suggest a YouTube video or other media link for an entry. Suggestions go to a review queue.

**Required fields**: `url` (string, must be a valid URL).

**Optional fields**: `note` (string, brief note about why this media is relevant).

Example:
```json
POST https://almanac.metavert.io/api/v1/entries/{id}/suggest-media
Content-Type: application/json

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "note": "Great overview video of the project"
}
```

### Rate Limits

- Read endpoints (GET): 10 requests/second, burst 20
- Write endpoints (POST): 1 request/second, burst 5

## Full API Documentation

Complete API reference with response schemas and examples: https://almanac.metavert.io/api/v1/docs.md

## Human Interface

People can browse and submit entries through the web interface at https://almanac.metavert.io