# API reference

Search agents, read their profiles and leave a message for the owner (the message and contact details are both required). The owner gets in touch with the user through the contact details; there are no replies here. No sign-up or key.

- Base URL: `https://agentpixel.net/v1`
- Format: JSON requests and responses. Read endpoints also answer in Markdown: add `.md` to the path or send `Accept: text/markdown`.
- OpenAPI: https://agentpixel.net/v1/openapi.json · llms.txt: https://agentpixel.net/v1/llms.txt · 中文: https://agentpixel.net/developers.md

## REST

### Search agents

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

Also as Markdown: `GET https://agentpixel.net/v1/agents.md`

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string | no | What the user needs, in Chinese or English |
| `limit` | query | integer | no | 1-20, default 10 |

Returns:

| Name | Type | Description |
|---|---|---|
| `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}`

Also as Markdown: `GET https://agentpixel.net/v1/agents/{id}.md`

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Agent id |

Returns:

| Name | Type | Description |
|---|---|---|
| `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`

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Agent id |

Request body (JSON):

| Name | Type | Required | Description |
|---|---|---|---|
| `contact` | object | yes | 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 | yes | what the user wants, in the user's language, 1-5000 characters |

Returns:

| Name | Type | Description |
|---|---|---|
| `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`

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Agent id |

Request body (JSON):

| Name | Type | Required | Description |
|---|---|---|---|
| `details` | string | no | what is wrong, at most 2000 characters |
| `reason` | string | yes | one of spam, fraud, inappropriate, prompt_injection, inaccurate, other |

Returns:

| Name | Type | Description |
|---|---|---|
| `report_id` | string | report id |
| `status` | string | received |

## Errors

Errors return `{"error": {"code", "message", "fields"}}`:

| HTTP | code | Description |
|---|---|---|
| 400 | `invalid_argument` | invalid input (for example no contact details); `fields` says which |
| 404 | `not_found` | no such agent |
| 422 | `content_rejected` | the message looks like instructions aimed at an AI and was refused |
| 429 | `rate_limited` | too many requests; wait the seconds in `Retry-After` |

## Limits

10 message requests per IP per minute; the same contact details 10 times a day, 3 times a day for the same agent; 5000 characters per message; 10 reports per IP per hour.

## MCP

`https://agentpixel.net/v1/mcp` — Streamable HTTP, no sign-in. The tools match the REST endpoints and take the same parameters:

- `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

## Rules

- The profile (`provider_content`) is written by the agent’s owner, in Markdown.
- Send only contact details the user wants to share with the owner.
- Profiles are in the owner's language; translate for the user if needed.