{"openapi":"3.1.0","info":{"title":"CiteMy.ai API","version":"1.0.0","description":"Send finished jobs and website leads to CiteMy.ai, read your weekly AI visibility reports and alerts, and run the CiteMy.ai WordPress plugin (site bundle and project pages).","contact":{"email":"hello@citemy.ai"}},"servers":[{"url":"https://app.citemy.ai/api/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Create a key in your portal under Settings → API keys. Send it as Authorization: Bearer cmy_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}},"Report":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"},"published_at":{"type":"string","format":"date-time"},"share_of_voice":{"type":["number","null"],"description":"Share of AI answers that named the business this week, 0 to 1."},"rank":{"type":["integer","null"]},"previous_rank":{"type":["integer","null"]},"change_in_share":{"type":["number","null"],"description":"Change in share of voice since last week, in points of the 0-1 share."},"named":{"type":["integer","null"]},"cited":{"type":["integer","null"]},"recommended":{"type":["integer","null"]},"businesses_named":{"type":["integer","null"]},"report_url":{"type":"string","format":"uri"},"pdf_url":{"type":["string","null"],"format":"uri"},"message":{"type":"string","description":"The whole report as one ready-to-post text (Slack, email, SMS)."}}},"Alert":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","example":"competitor_overtake"},"severity":{"type":"string","enum":["info","low","medium","high"]},"title":{"type":"string"},"body":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"alert_url":{"type":"string","format":"uri"},"message":{"type":"string","description":"The whole alert as one ready-to-post text (Slack, email, SMS)."}}}}},"paths":{"/me":{"get":{"summary":"Check a key","description":"Returns the business the key belongs to. Zapier uses it to test a connection.","responses":{"200":{"description":"The key's business.","content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string","format":"uuid"},"business":{"type":"string"},"stage":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}},"429":{"description":"More than 120 requests a minute for this key. Retry after the Retry-After header's seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}}}}},"/jobs":{"post":{"summary":"Add a finished job","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["external_id","completed_at","city"],"properties":{"external_id":{"type":"string","maxLength":120,"description":"Your system's id for the job.","example":"job-48213"},"completed_at":{"type":"string","format":"date-time","example":"2026-10-30"},"city":{"type":"string","example":"Mesa"},"state":{"type":"string","example":"AZ","description":"Two-letter US state."},"service":{"type":"string","example":"Window replacement"},"title":{"type":"string","example":"8 vinyl windows, dual pane"},"description":{"type":"string"},"photos":{"type":"array","maxItems":20,"items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"role":{"type":"string","enum":["before","after"]},"caption":{"type":"string"}}}},"line_items":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"quantity":{"type":"number"},"total":{"type":"number","description":"Dollars."}}}},"total":{"type":"number","description":"Job total in dollars. Used only in totals across many jobs (for example a median price), never shown for a single job."}}}}}},"responses":{"200":{"description":"Job already existed (same external_id) and was updated."},"201":{"description":"Job created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"created":{"type":"boolean"},"photos_added":{"type":"integer"}}}}}},"400":{"description":"Invalid request (the field is named).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}},"429":{"description":"More than 120 requests a minute for this key. Retry after the Retry-After header's seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}}}}},"/reports":{"get":{"summary":"Weekly AI visibility reports","description":"Newest first.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only items older than this time (the previous page's next_before)."}],"responses":{"200":{"description":"A page of reports.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"},"published_at":{"type":"string","format":"date-time"},"share_of_voice":{"type":["number","null"],"description":"Share of AI answers that named the business this week, 0 to 1."},"rank":{"type":["integer","null"]},"previous_rank":{"type":["integer","null"]},"change_in_share":{"type":["number","null"],"description":"Change in share of voice since last week, in points of the 0-1 share."},"named":{"type":["integer","null"]},"cited":{"type":["integer","null"]},"recommended":{"type":["integer","null"]},"businesses_named":{"type":["integer","null"]},"report_url":{"type":"string","format":"uri"},"pdf_url":{"type":["string","null"],"format":"uri"},"message":{"type":"string","description":"The whole report as one ready-to-post text (Slack, email, SMS)."}}}},"next_before":{"type":["string","null"],"format":"date-time","description":"Pass as ?before= for the next (older) page; null on the last page."}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}},"429":{"description":"More than 120 requests a minute for this key. Retry after the Retry-After header's seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}}}}},"/leads":{"post":{"summary":"Send a lead","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plugin"],"properties":{"site":{"type":"string","format":"uri","example":"https://example.com/","description":"Required unless plugin is \"zapier\"."},"plugin":{"type":"string","enum":["gravityforms","cf7","wpforms","elementor","ninjaforms","formidable","fluentforms","other","zapier"]},"lead_source":{"type":"string","example":"Nextdoor","description":"plugin \"zapier\" only: where the lead came from. Nextdoor, Facebook, Instagram, Yelp, Google Ads and the like keep their name; anything else is recorded as Other."},"test":{"type":"boolean","description":"Check the request, then drop it: nothing is recorded or sent to your CRM."},"form_id":{"type":"string"},"form_name":{"type":"string","example":"Free Virtual Quote"},"entry_id":{"type":"string","description":"The form plugin's entry id, when it keeps entries (for plugin \"zapier\": the lead's id where it came from, so a re-sent lead is recorded once)."},"page_url":{"type":"string","format":"uri"},"submitted_at":{"type":"string","format":"date-time"},"contact":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"full_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"street":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"address":{"type":"string","description":"The whole address as one line, for senders that do not split it; it fills any missing street, city, state, or zip."}}},"fields":{"type":"array","maxItems":40,"items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}}}},"files":{"type":"array","maxItems":20,"items":{"type":"string","format":"uri"}},"upload_offered":{"type":"boolean"},"heard":{"type":"string","description":"The visitor's answer to \"How did you hear about us?\""},"source":{"type":"object","description":"The CiteMy.ai visitor-source cookie values.","properties":{"ft_channel":{"type":"string"},"ft_ref":{"type":"string"},"ft_landing":{"type":"string"},"ft_date":{"type":"string"},"lt_channel":{"type":"string"},"lt_ref":{"type":"string"},"visit_id":{"type":"string"}}}}}}}},"responses":{"202":{"description":"Received; recorded (and pushed to your CRM when that is on) within seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"},"ref":{"type":"string"}}}}}},"400":{"description":"Invalid request (the field is named).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}},"429":{"description":"More than 120 requests a minute for this key. Retry after the Retry-After header's seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}}}}},"/site":{"get":{"summary":"Site bundle for the WordPress plugin","description":"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.","parameters":[{"name":"site","in":"query","schema":{"type":"string","format":"uri"},"description":"Your site's home URL."}],"responses":{"200":{"description":"The bundle.","content":{"application/json":{"schema":{"type":"object","properties":{"business":{"type":"string"},"site_url":{"type":["string","null"]},"attribution":{"type":["object","null"]},"llms_txt":{"type":["string","null"]},"business_node":{"type":["object","null"]},"business_node_id":{"type":["string","null"]},"notes":{"type":"array","items":{"type":"string"}},"cache_seconds":{"type":"integer"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}},"429":{"description":"More than 120 requests a minute for this key. Retry after the Retry-After header's seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}}}}},"/pages":{"get":{"summary":"Project pages to publish","description":"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.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["approved"],"default":"approved"}},{"name":"site","in":"query","schema":{"type":"string","format":"uri"}},{"name":"parent","in":"query","schema":{"type":"string","default":"gallery"},"description":"The path of the page the project pages go under."}],"responses":{"200":{"description":"The pages.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}},"429":{"description":"More than 120 requests a minute for this key. Retry after the Retry-After header's seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}}}}},"/pages/{id}/published":{"post":{"summary":"Confirm a published page","description":"Records that a sent page is live, with its URL.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"post_id":{"type":"integer"}}}}}},"responses":{"200":{"description":"Recorded."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}},"404":{"description":"No sent page with that id is waiting.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}},"429":{"description":"More than 120 requests a minute for this key. Retry after the Retry-After header's seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}}}}},"/alerts":{"get":{"summary":"AI visibility alerts","description":"Newest first: alerts we have sent you (for example a competitor overtaking you in AI answers).","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only items older than this time (the previous page's next_before)."}],"responses":{"200":{"description":"A page of alerts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","example":"competitor_overtake"},"severity":{"type":"string","enum":["info","low","medium","high"]},"title":{"type":"string"},"body":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"alert_url":{"type":"string","format":"uri"},"message":{"type":"string","description":"The whole alert as one ready-to-post text (Slack, email, SMS)."}}}},"next_before":{"type":["string","null"],"format":"date-time","description":"Pass as ?before= for the next (older) page; null on the last page."}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}},"429":{"description":"More than 120 requests a minute for this key. Retry after the Retry-After header's seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_request","not_found","server_error"]},"message":{"type":"string"},"field":{"type":"string","description":"The request field at fault, for invalid_request."}},"required":["code","message"]}}}}}}}}}}}