> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topyappers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Outreach API

> Access your outreach projects, contacted creators, and email history

# Agent Outreach API

The Agent Outreach API exposes the email outreach data created by your TopYappers agent. Use it to resolve an inbox email address back to the creator, project, Gmail thread, and previous messages so your team or AI agent can write a more customized reply.

## Base URL

`https://api.topyappers.com`

## Authentication

All requests require a TopYappers API key in the `x-ty-api-key` header.

```bash theme={null}
x-ty-api-key: your-api-key
```

The API key is scoped to the key owner’s team, so responses only include that team’s agent projects and email messages.

## Pricing

These endpoints are **free**. They validate your API key and apply rate limits, but they do not consume credits because they return your own outreach data.

## Rate limits

* 60 requests per minute per API key.
* HTTP `429` responses include `Retry-After`.

## Endpoints

| Endpoint                               | Description                                                                                           |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `GET /api/v1/agent/projects`           | List your active agent outreach projects.                                                             |
| `GET /api/v1/agent/contacted-creators` | List creators contacted by outbound agent email.                                                      |
| `GET /api/v1/agent/messages`           | List email messages, filterable by project, creator email, creator ID, thread, status, and direction. |

## Common workflow

1. Call `GET /api/v1/agent/messages?creatorEmail=creator@example.com&direction=all` with the email address from your inbox.
2. Use the returned `creator_id`, `creator_name`, `project_id`, `thread_id`, and message history to understand context.
3. Optionally call `GET /api/v1/agent/projects` to map the `project_id` to the campaign details.
4. Use `GET /api/v2/creators/search?email=creator@example.com` or `POST /api/v2/creators/get` when you also need the creator’s public profile data.

## Response envelope

All Agent Outreach API responses use the standard public API envelope:

```json theme={null}
{
  "message": "OK",
  "response": {
    "data": []
  }
}
```

Paginated endpoints also include `page`, `per_page`, `next_page`, `total_pages`, and `total` inside `response`.