{"openapi":"3.1.0","info":{"title":"Citality API","version":"1.0.0","description":"Read access to your AI search visibility data. Agency plan. Authenticate with an API key as a Bearer token."},"servers":[{"url":"https://citality.ai/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your Citality API key (ctl_live_...)."}},"schemas":{"Client":{"type":"object","properties":{"clientId":{"type":"string"},"name":{"type":"string"},"industry":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"Prompt":{"type":"object","properties":{"promptId":{"type":"string"},"clientId":{"type":"string"},"prompt":{"type":"string"},"intent":{"type":"string"},"location":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"Result":{"type":"object","properties":{"resultId":{"type":"string"},"clientId":{"type":"string"},"promptId":{"type":"string"},"date":{"type":"string","format":"date"},"platform":{"type":"string"},"brandMentioned":{"type":"boolean"},"position":{"type":"string"},"competitors":{"type":"string"},"yourUrl":{"type":"string"},"competitorUrls":{"type":"string"},"confidence":{"type":["number","null"]},"needsReview":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"Metrics":{"type":"object","properties":{"totalPrompts":{"type":"integer"},"promptsWithBrand":{"type":"integer"},"brandPercentage":{"type":"integer"},"totalResults":{"type":"integer"},"topPlatform":{"type":"string"},"topCompetitor":{"type":"string"},"byPlatform":{"type":"array","items":{"type":"object"}},"byIntent":{"type":"array","items":{"type":"object"}},"topCompetitors":{"type":"array","items":{"type":"object"}},"topUrls":{"type":"array","items":{"type":"object"}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"paths":{"/clients":{"get":{"summary":"List clients","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Client"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clients/{clientId}":{"get":{"summary":"Get a client","parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Client"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clients/{clientId}/prompts":{"get":{"summary":"List a client's prompts","parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Prompt"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clients/{clientId}/results":{"get":{"summary":"List a client's results","parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Filter results on/after this date (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Filter results on/before this date (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"Filter by platform (ChatGPT, Claude, Gemini, Perplexity).","schema":{"type":"string"}},{"name":"promptId","in":"query","required":false,"description":"Filter to one prompt.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size (1-200, default 50).","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Result"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"cursor":{"type":["string","null"]},"next":{"type":["string","null"]}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clients/{clientId}/metrics":{"get":{"summary":"Visibility metrics for a client","parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Metrics"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/prompts/{promptId}":{"get":{"summary":"Get a prompt","parameters":[{"name":"promptId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Prompt"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/results/{resultId}":{"get":{"summary":"Get a result","parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Result"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tests":{"post":{"summary":"Run a prompt test (requires the write scope; debits checks)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["promptId"],"properties":{"promptId":{"type":"string"},"models":{"type":"array","items":{"type":"string"},"description":"Model ids; defaults to all enabled, capped to the plan."},"opusJudge":{"type":"boolean","description":"Use the high-accuracy judge (Growth+; doubles checks)."}}}}}},"responses":{"201":{"description":"Test run","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"testGroupId":{"type":"string"},"logged":{"type":"integer"},"billedChecks":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Result"}},"notices":{"type":"array","items":{"type":"string"}},"errors":{"type":"array","items":{"type":"string"}}}},"meta":{"type":"object","properties":{"checksRemaining":{"type":"integer"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing write scope / plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Prompt or client not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"All model runs failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}