# Agent — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and discover AI agents in the Agent.ai marketplace by filtering through categories and tags, then view detailed agent information and builder profiles. Find the perfect AI solution for your needs by browsing available agents, exploring builder credentials, and comparing agent capabilities across different categories.

**Category:** Marketplaces | **Website:** [agent.ai/](https://agent.ai/) | **Docs:** [parse.bot/marketplace/cb688740-e0f2-41d9-b417-8e269112e4a1/agent-ai-api](https://parse.bot/marketplace/cb688740-e0f2-41d9-b417-8e269112e4a1/agent-ai-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-agent-ai-api-cb688740/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### filter_agents_by_tag

Filter agents by category tag. Returns paginated results of agents matching the specified tag. Tags are obtained from the get_agent_tags endpoint. Each page contains up to 20 agents.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (0-indexed). |
| `tag` | string | Yes | Category tag to filter by. Obtain available tags from the get_agent_tags endpoint. Confirmed working values include Sales, Marketing, Customer Service, HubSpot, Lifestyle, Image, Operations, Social. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-agent-ai-api-cb688740/filter_agents_by_tag \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","tag":"<string>"}'
```

### get_agent_details

Get comprehensive details for a single agent by its alphanumeric agent_id. Returns full agent information including description, action types, author details, pricing, and review scores. The agent_id can be either the internal alphanumeric ID or the human-readable slug (agent_id_human).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agent_id` | string | Yes | The alphanumeric agent ID (e.g. '8hc9z3aiwok5ypt2') or human-readable slug (e.g. 'web-copy-analyzer'), obtainable from list_agents or filter_agents_by_tag results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-agent-ai-api-cb688740/get_agent_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"<string>"}'
```

### get_agent_tags

Get the list of available category tags that can be used with filter_agents_by_tag. Returns all tags with at least one agent in the marketplace.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-agent-ai-api-cb688740/get_agent_tags \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_builder_profile

Get a builder's profile information and their created agents. Looks up the builder by matching the username against twitter_username, agent_ai_username, or display_name from the builders list. Returns the builder's profile metadata and all their public agents.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | string | Yes | Builder's twitter_username, agent_ai_username, or display_name as returned by list_builders. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-agent-ai-api-cb688740/get_builder_profile \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"<string>"}'
```

### list_agents

Search for AI agents by keyword, or list all agents if no query is provided. Returns paginated results sorted by relevance. Each page contains up to 20 agents. Paginates via a 0-indexed page counter; total pages and hit count are included in the response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (0-indexed). |
| `query` | string | No | Search keyword to filter agents by name or description. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-agent-ai-api-cb688740/list_agents \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

### list_builders

List top AI agent builders/creators ranked by total execution count. Returns profile information including display name, Twitter handle, public agent count, and total executions. The full ranked list is returned in a single page.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-agent-ai-api-cb688740/list_builders \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```