Developers

CiteMy.ai API

Connect the tools you already use. Send each finished job with its photos and we turn the best ones into project pages on your website, after your approval. Pull your weekly AI visibility report and alerts into Slack, email, or a spreadsheet.

Base URL https://app.citemy.ai/api/v1 · OpenAPI spec · Updated

Authentication

Every request needs an API key. An owner creates one in the portal under Settings → API keys (it is shown once). Send it as a header: Authorization: Bearer cmy_…. A revoked key stops working at once.

What we keep private

Send the city, never a street address or a customer's name. Emails, phone numbers, and street addresses in text are removed before anything is stored. Photos are checked for quality and privacy, their metadata (GPS included) is stripped, and nothing is published until you approve the page.

Endpoints

GET/me: Check a key

Returns the business the key belongs to. Zapier uses it to test a connection.

curl https://app.citemy.ai/api/v1/me \
  -H "Authorization: Bearer cmy_YOUR_KEY"
{
  "client_id": "6f0c…",
  "business": "Sunbelt Roofing",
  "stage": "live"
}

POST/jobs: Add a finished job

Records a finished job with its photos. We check every photo (quality and privacy), keep the good after photos, strip their metadata, and draft a project page in your next weekly batch for your approval. Nothing is published without approval. Send the city only, never a street address or customer name; emails, phone numbers, and street addresses in text are removed. Sending the same external_id again updates the job and adds only new photos.

curl https://app.citemy.ai/api/v1/jobs \
  -H "Authorization: Bearer cmy_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"job-48213","completed_at":"2026-10-30","city":"Mesa","state":"AZ","service":"Window replacement","title":"8 vinyl windows, dual pane","photos":[{"url":"https://example.com/photos/after-1.jpg","role":"after"},{"url":"https://example.com/photos/before-1.jpg","role":"before"}],"total":7940}'
{
  "id": "api:job-48213",
  "created": true,
  "photos_added": 2
}

POST/leads: Send a lead

A form submission from your site, with the visitor's source (the CiteMy.ai WordPress plugin sends these), or a lead from somewhere else, like a Nextdoor or Facebook lead-form ad (plugin "zapier", with lead_source; site is optional then). We record it in your lead report and, when your account is connected to Housecall Pro or Jobber with lead push on, create the lead there with its source. Idempotent: the same entry (or the same person on the same form in the same minute) is recorded once. Send test: true to check a request without recording or sending anything.

curl https://app.citemy.ai/api/v1/leads \
  -H "Authorization: Bearer cmy_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site":"https://example.com/","plugin":"wpforms","form_id":"12","form_name":"Free Virtual Quote","entry_id":"381","page_url":"https://example.com/windows/","contact":{"first_name":"Dana","last_name":"Lee","email":"dana@example.com","phone":"(602) 555-0100","city":"Mesa"},"fields":[{"label":"Measurements","value":"Two windows, 36x48"}],"source":{"lt_channel":"chatgpt","lt_ref":"chatgpt.com"}}'
{
  "received": true,
  "ref": "wp:example.com:wpforms:12:381"
}

GET/site: Site bundle for the WordPress plugin

The visitor-source script's settings, llms.txt, and the business node for your structured data. A part that is not ready is null, with a note saying why. Cache it for cache_seconds.

curl "https://app.citemy.ai/api/v1/site?site=https://example.com/" \
  -H "Authorization: Bearer cmy_YOUR_KEY"
{
  "business": "Sunbelt Roofing",
  "site_url": "https://example.com",
  "attribution": {
    "beacon_id": "…",
    "rules_version": "1",
    "config": {}
  },
  "llms_txt": "# Sunbelt Roofing\n…",
  "business_node": {
    "@type": "RoofingContractor",
    "@id": "https://example.com/#business"
  },
  "business_node_id": "https://example.com/#business",
  "notes": [],
  "cache_seconds": 86400
}

GET/pages: Project pages to publish

Project pages you approved and CiteMy.ai sent to your site, not yet published. Empty unless page publishing through the plugin is on for your account. Each page's images come as one-hour links; the body names each image by a token (citemy-img:N) to replace with your copy.

curl "https://app.citemy.ai/api/v1/pages?status=approved&site=https://example.com/&parent=gallery" \
  -H "Authorization: Bearer cmy_YOUR_KEY"
{
  "data": [
    {
      "id": "5b1d…",
      "title": "Window replacement in Mesa",
      "slug": "mesa-windows-2026-10",
      "html": "<p>…</p><img src=\"citemy-img:0\" …>",
      "images": [
        {
          "token": "citemy-img:0",
          "url": "https://…",
          "alt": "Finished windows",
          "featured": true
        }
      ],
      "meta_title": "…",
      "meta_description": "…",
      "json_ld": {},
      "approved_at": "2026-11-03T15:00:00Z"
    }
  ]
}

POST/pages/{id}/published: Confirm a published page

Records that a sent page is live, with its URL.

curl https://app.citemy.ai/api/v1/pages/5b1d…/published \
  -H "Authorization: Bearer cmy_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/gallery/mesa-windows-2026-10/","post_id":412}'
{
  "published": true
}

GET/reports: Weekly AI visibility reports

Newest first.

curl "https://app.citemy.ai/api/v1/reports?limit=1" \
  -H "Authorization: Bearer cmy_YOUR_KEY"
{
  "data": [
    {
      "id": "9a1e…",
      "period_start": "2026-10-26",
      "period_end": "2026-11-01",
      "published_at": "2026-11-02T14:00:00Z",
      "share_of_voice": 0.18,
      "rank": 3,
      "previous_rank": 4,
      "change_in_share": 0.03,
      "named": 21,
      "cited": 9,
      "recommended": 6,
      "businesses_named": 34,
      "report_url": "https://app.citemy.ai/s/…",
      "pdf_url": null,
      "message": "AI visibility report, 2026-10-26 to 2026-11-01\nShare of voice: 18%, rank 3 (was 4), +3 points vs last week\nIn AI answers: named 21 times, cited 9, recommended 6 (34 businesses named in total)\nFull report: https://app.citemy.ai/s/…"
    }
  ],
  "next_before": null
}

GET/alerts: AI visibility alerts

Newest first: alerts we have sent you (for example a competitor overtaking you in AI answers).

curl https://app.citemy.ai/api/v1/alerts \
  -H "Authorization: Bearer cmy_YOUR_KEY"
{
  "data": [
    {
      "id": "c3b2…",
      "kind": "competitor_overtake",
      "severity": "medium",
      "title": "A competitor passed you in ChatGPT answers",
      "body": "…",
      "sent_at": "2026-11-01T16:20:00Z",
      "alert_url": "https://app.citemy.ai/portal",
      "message": "A competitor passed you in ChatGPT answers\n\n…\n\nSeverity: medium · 2026-11-01\n\nDetails: https://app.citemy.ai/portal"
    }
  ],
  "next_before": null
}

Errors and limits

120 requests a minute per key. Over that, you get 429 with a Retry-After header in seconds. Lists return up to 50 items; pass the response's next_before as ?before= for the next page. Errors look like {"error": {"code": "invalid_request", "message": "…", "field": "city"}}.

StatusCodeMeaning
400invalid_requestA field is missing or wrong; `field` names it.
401unauthorizedMissing, invalid, or revoked API key.
404not_foundThe key's account no longer exists.
429rate_limitedOver 120 requests a minute; wait Retry-After seconds.
500server_errorOur side failed; retry shortly.

Zapier

The CiteMy.ai Zapier app uses this API: the action "Add finished job", and the triggers "New weekly report" and "New AI visibility alert". Connect it with an API key.

CiteMy.ai in the Zapier app directory