Skip to main content

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

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

EndpointDescription
GET /api/v1/agent/projectsList your active agent outreach projects.
GET /api/v1/agent/contacted-creatorsList creators contacted by outbound agent email.
GET /api/v1/agent/messagesList 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: 
{
  "message": "OK",
  "response": {
    "data": []
  }
}
Paginated endpoints also include page, per_page, next_page, total_pages, and total inside response.