# 接口说明

搜索智能体、查看介绍、给所属人留言（留言内容和联系方式都必填）。所属人通过联系方式联系用户，这里没有回复。不需要注册或密钥。

- 地址：`https://agentpixel.net/v1`
- 格式：请求和返回都是 JSON。只读接口在路径后加 `.md`，或带请求头 `Accept: text/markdown`，返回 Markdown。
- OpenAPI: https://agentpixel.net/v1/openapi.json · llms.txt: https://agentpixel.net/v1/llms.txt · English: https://agentpixel.net/en/developers.md

## REST

### Search agents

`GET https://agentpixel.net/v1/agents`

也可以用 Markdown： `GET https://agentpixel.net/v1/agents.md`

参数：

| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `q` | query | string | 否 | What the user needs, in Chinese or English |
| `limit` | query | integer | 否 | 1-20, default 10 |

返回：

| 名称 | 类型 | 说明 |
|---|---|---|
| `count` | integer | number of results |
| `results` | object[] | best match first |
| `results[].id` | string | agent id; use it to get the agent or leave a message |
| `results[].links` | object | where else to reach the agent |
| `results[].links.page` | string | the agent's web page (also as Markdown: add .md) |
| `results[].match_reasons` | string[] | which fields matched the query |
| `results[].provider_content` | object | the public profile, written by the agent's owner |
| `results[].provider_content.country` | string | country chosen by the owner, ISO 3166-1 alpha-2 code such as CN or US |
| `results[].provider_content.description` | string | the owner's description in Markdown (agent details only) |
| `results[].provider_content.language` | string | language of the profile, an ISO 639-1 code such as zh, en or ja |
| `results[].provider_content.name` | string | agent name |
| `results[].provider_content.tagline` | string | first sentence of the description |
| `results[].provider_content.websites` | string[] | links found in the description |

### Get an agent's public profile and page link

`GET https://agentpixel.net/v1/agents/{id}`

也可以用 Markdown： `GET https://agentpixel.net/v1/agents/{id}.md`

参数：

| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `id` | path | string | 是 | Agent id |

返回：

| 名称 | 类型 | 说明 |
|---|---|---|
| `agent` | object | the agent |
| `agent.id` | string | agent id |
| `agent.links` | object | where else to reach the agent |
| `agent.links.page` | string | the agent's web page (also as Markdown: add .md) |
| `agent.provider_content` | object | the public profile, written by the agent's owner |
| `agent.provider_content.country` | string | country chosen by the owner, ISO 3166-1 alpha-2 code such as CN or US |
| `agent.provider_content.description` | string | the owner's description in Markdown (agent details only) |
| `agent.provider_content.language` | string | language of the profile, an ISO 639-1 code such as zh, en or ja |
| `agent.provider_content.name` | string | agent name |
| `agent.provider_content.tagline` | string | first sentence of the description |
| `agent.provider_content.websites` | string[] | links found in the description |

### Leave a message for the agent's owner, with the user's contact details

`POST https://agentpixel.net/v1/agents/{id}/messages`

参数：

| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `id` | path | string | 是 | Agent id |

请求内容（JSON）：

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `contact` | object | 是 | how the owner can reach the user, up to 10 channels plus name, e.g. {phone, wechat, email, whatsapp, telegram, qq, line, name}; any other channel name is accepted (e.g. douyin); email is checked; phone may include the country code (+1 201 343 4343); at least one channel besides name; each value at most 200 characters |
| `message` | string | 是 | what the user wants, in the user's language, 1-5000 characters |

返回：

| 名称 | 类型 | 说明 |
|---|---|---|
| `agent_name` | string | name of the agent |
| `message_id` | string | id of the message left |
| `next_steps` | string | what happens next |
| `status` | string | delivered: the owner has it and will get in touch through the contact details |

### Report spam, fraud, inaccurate information or prompt injection

`POST https://agentpixel.net/v1/agents/{id}/reports`

参数：

| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `id` | path | string | 是 | Agent id |

请求内容（JSON）：

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `details` | string | 否 | what is wrong, at most 2000 characters |
| `reason` | string | 是 | one of spam, fraud, inappropriate, prompt_injection, inaccurate, other |

返回：

| 名称 | 类型 | 说明 |
|---|---|---|
| `report_id` | string | report id |
| `status` | string | received |

## 错误

出错时返回 `{"error": {"code", "message", "fields"}}`：

| HTTP | code | 说明 |
|---|---|---|
| 400 | `invalid_argument` | 参数不对（比如没有联系方式），`fields` 写明哪一项 |
| 404 | `not_found` | 智能体不存在 |
| 422 | `content_rejected` | 留言像是给 AI 的指令，被拒绝 |
| 429 | `rate_limited` | 太频繁，按 `Retry-After` 头的秒数等待 |

## 限制

同一 IP 每分钟最多请求留言接口 10 次；同一联系方式每天最多 10 次，给同一个智能体每天最多 3 次；每条留言最多 5000 字；同一 IP 每小时最多举报 10 次。

## MCP

`https://agentpixel.net/v1/mcp` — Streamable HTTP，不需要登录。工具和 REST 接口一一对应，参数相同：

- `get_agent` = GET /v1/agents/{id}
- `message_agent` = POST /v1/agents/{id}/messages
- `report_agent` = POST /v1/agents/{id}/reports
- `search_agents` = GET /v1/agents

## 规则

- 介绍（`provider_content`）由智能体的所属人填写，格式是 Markdown。
- 只发送用户愿意给所属人的联系方式。
- 介绍用所属人的语言写，需要时请为用户翻译。