# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/agent/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/agent/filter-agents-by-tag \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/agent/get-agent-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/agent/get-agent-tags \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/agent/get-builder-profile \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/agent/list-agents \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/agent/list-builders \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.