Docs/API Reference

REST API Reference

Build custom integrations with the Agentcy REST API. Query your marketing data from any language or platform.

Using Claude, ChatGPT, or Cursor? See the Tool Reference for MCP integration instead.

BASE URL

base url

https://data.goagentcy.com

AUTHENTICATION

Authenticate by including your API key in the Authorization header as a Bearer token.

header

Authorization: Bearer agcy_your_api_key

API keys use the agcy_ prefix. Create and manage keys in the Agentcy portal.

Keys are shown once at creation. Store them securely — we only keep a hashed prefix.

Revoked keys return 401 immediately.

ENDPOINTS

4 ROUTES

POST/api/query POST/api/research GET/api/sources GET/api/current-date

POST/api/query

Auth Required

Query marketing data

The primary endpoint. Send a natural language question about your marketing data and get back a synthesized insight. The server automatically routes to the right data sources (GA4, Search Console, Google Ads, WooCommerce, etc.) based on your question.

Request Body1 REQUIRED / 6 TOTAL

Parameter	Type	Required	Description
`request`	string	Yes	Natural language question about your marketing data.Required
`domain`	string	No	Domain to query (e.g., "example.com"). If omitted and you have one domain configured, it's used automatically.
`start_date`	string	No	Start date in YYYY-MM-DD format or relative (e.g., "30daysAgo").Default: 30 days ago
`end_date`	string	No	End date in YYYY-MM-DD format or relative (e.g., "today", "yesterday").Default: yesterday
`source_hints`	string[]	No	Preferred data sources. If omitted, the server auto-selects via semantic routing.
`reference_images`	string[]	No	URLs of reference images (max 5) for image generation requests.

Request

curl

curl -X POST https://data.goagentcy.com/api/query \
  -H "Authorization: Bearer agcy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "request": "How is organic traffic trending this month?",
    "domain": "example.com"
  }'

Response200 OK

response.json

{
  "content": "## Organic Traffic Analysis — example.com\n\nLast 30 days vs previous period:\n\n- Sessions: 12,847 (+18.3%)\n- Top landing page: /guide (2,104 sessions)\n- New keywords ranking: 47 terms in top 20\n- Conversion rate: 3.2% (up from 2.8%)\n\nRecommendation: Your guide content is driving significant growth. Consider expanding with related long-tail topics.",
  "services": ["ga4", "gsc"],
  "tier": "server_llm",
  "cached": false,
  "latency_ms": 4230
}

POST/api/research

Auth Required

Research any topic

Run web research without needing a connected data source. Search Google, Bing, YouTube, news, and 100+ engines. Read webpages, extract transcripts, find reviews, and track competitors. Runs independently of your configured domains.

Request Body1 REQUIRED / 2 TOTAL

Parameter	Type	Required	Description
`request`	string	Yes	Natural language research question.Required
`domain`	string	No	Optional domain for context (e.g., "example.com"). Helps focus competitor research. Not required.

Request

curl

curl -X POST https://data.goagentcy.com/api/research \
  -H "Authorization: Bearer agcy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "request": "What pricing strategies are competitors using for protein supplements?",
    "domain": "aurora-fitness.com"
  }'

Response200 OK

response.json

{
  "content": "## Competitor Pricing Analysis — Protein Supplements\n\nTop 5 competitors analyzed:\n\n1. GNC — Premium tier ($45-60/lb), loyalty discounts\n2. Optimum Nutrition — Mid-range ($30-40/lb), bundle deals\n3. MyProtein — Value ($20-30/lb), aggressive sales\n4. Transparent Labs — Premium ($50+/lb), quality focus\n5. Ghost — Lifestyle ($35-45/lb), brand partnerships\n\nKey patterns:\n- Subscribe-and-save (15-25% off) is universal\n- Bundle pricing drives 30%+ higher AOV\n- Free shipping thresholds: $49-75 range\n\nSources: 12 web pages, 3 YouTube reviews",
  "services": ["web_intelligence"],
  "cached": false,
  "latency_ms": 8420
}

GET/api/sources

Auth Required

List available data sources

Returns your configured domains and their connected services. Use this to discover what data is available before querying. Optionally filter by domain.

Query Parameters0 REQUIRED / 1 TOTAL

Parameter	Type	Required	Description
`domain`	string (query param)	No	Filter to a specific domain. If omitted, returns all domains.

Request

curl

# List all domains and sources
curl -H "Authorization: Bearer agcy_your_api_key" \
  "https://data.goagentcy.com/api/sources"

# Filter by domain
curl -H "Authorization: Bearer agcy_your_api_key" \
  "https://data.goagentcy.com/api/sources?domain=example.com"

Response200 OK

response.json

{
  "domains": [
    {
      "domain": "example.com",
      "services": ["ga4", "gsc", "google_ads"]
    },
    {
      "domain": "shop.example.com",
      "services": ["ga4", "woocommerce"]
    }
  ],
  "global_services": [
    { "id": "web_intelligence", "name": "Web Intelligence" },
    { "id": "pagespeed", "name": "PageSpeed" },
    { "id": "dns_lookup", "name": "DNS Lookup" },
    { "id": "readability", "name": "Readability" }
  ]
}

GET/api/current-date

Public

Get current date

Returns the current date, day of week, and timezone. Useful for constructing date ranges in queries. No authentication required.

Request

curl

curl "https://data.goagentcy.com/api/current-date"

Response200 OK

response.json

{
  "date": "2026-03-12",
  "day_of_week": "Thursday",
  "timezone": "UTC"
}

ERROR CODES

All errors return a JSON object with error and code fields.

error response

{
  "error": "Missing required field: request",
  "code": "bad_request"
}

Status	Code	Description
`400`	`bad_request`	Invalid JSON body or missing required fields.
`400`	`validation_error`	Request parameters failed validation (e.g., invalid date format).
`401`	`auth_error`	Missing, invalid, or revoked API key.
`404`	`domain_error`	Specified domain not found or not configured.
`429`	`rate_limited`	Too many requests. Wait and retry. Limit: 60 requests per minute.
`500`	`internal_error`	Server error. If persistent, contact support.

RATE LIMITS

Request Limit

60 / min

Query Quota

Based on your plan. Check usage in the portal.

Timeout

300s

MCP TOOLS

Tool Reference

Parameters and examples for MCP tool integration.

QUICK START

Getting Started

Set up Agentcy in under 5 minutes.

v1.0Something missing?