> ## Documentation Index > Fetch the complete documentation index at: https://www.citedy.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Start a Citedy warm-lead report > Creates one tenant-scoped warm-lead run for one company domain. Accepted new runs charge exactly 40 Citedy credits. Poll GET /api/agent/citedy-warm-lead/{runId} for status and result. ## OpenAPI ````yaml post /api/agent/citedy-warm-lead openapi: 3.1.0 info: title: Citedy Agent API version: 1.0.0 description: >- Public contract for Citedy agent integrations. This contract reflects the current /api/agent surface without changing runtime behavior. contact: name: Citedy Support url: https://www.citedy.com license: name: Proprietary url: https://www.citedy.com servers: - url: https://www.citedy.com security: [] tags: - name: Health description: Platform and dependency health - name: Registration description: Agent onboarding and approval - name: Agent description: Agent identity and key lifecycle - name: Scout description: Trend scouting endpoints - name: Gaps description: Content gap analysis - name: Autopilot description: Article generation and retrieval - name: Articles description: Queued article generation job polling - name: Adaptations description: Social adaptation generation - name: Sessions description: Autopilot recurring sessions - name: Lead Magnets description: Lead magnet generation and state - name: Warm Leads description: Warm-lead report generation and export - name: Ingest description: Content ingestion jobs - name: Competitors description: Competitor discovery and analysis - name: Personas description: Writing persona catalog - name: Webhooks description: Webhook endpoint registration and delivery logs - name: Publishing description: Social publishing, scheduling and cancellation - name: Schedule description: Content schedule timeline and gap analysis - name: Settings description: Agent preferences and configuration - name: Scan description: Experimental trend scanning (xAI Grok) - name: Status description: Operational readiness and actionable onboarding status - name: Products description: Product knowledge base document management - name: Shorts description: Short-form video generation and polling - name: SEO Tools description: Agent-authenticated SEO diagnostics tools exposed via MCP seo.* namespace. - name: GSC description: Google Search Console integration and reporting paths: /api/agent/citedy-warm-lead: post: tags: - Warm Leads summary: Start a Citedy warm-lead report description: >- Creates one tenant-scoped warm-lead run for one company domain. Accepted new runs charge exactly 40 Citedy credits. Poll GET /api/agent/citedy-warm-lead/{runId} for status and result. operationId: createCitedyWarmLeadRun requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWarmLeadRunRequest' responses: '200': description: >- Existing idempotent warm-lead run returned without a new credit charge content: application/json: schema: $ref: '#/components/schemas/CreateWarmLeadRunResponse' '202': description: Warm-lead run accepted content: application/json: schema: $ref: '#/components/schemas/CreateWarmLeadRunResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' security: - AgentApiKey: [] components: schemas: CreateWarmLeadRunRequest: type: object properties: domain: type: string minLength: 1 maxLength: 253 description: >- One company domain. Bare domains and http(s) URLs are accepted, but paths/social profile URLs are rejected. icp: type: string enum: - seo-geo-agency - content-led-saas - vertical-saas description: Ideal customer profile. Defaults to content-led-saas when omitted. buyerRoles: type: array maxItems: 6 items: type: string minLength: 1 maxLength: 80 maxContacts: type: integer minimum: 1 maximum: 3 description: Maximum buyer candidates. Defaults to 3 when omitted. drafts: type: integer minimum: 1 maximum: 3 description: Maximum outreach drafts. Defaults to 3 when omitted. freshnessDays: type: integer minimum: 7 maximum: 365 description: Evidence lookback window in days. Defaults to 90 when omitted. idempotencyKey: type: string minLength: 8 maxLength: 128 required: - domain additionalProperties: false CreateWarmLeadRunResponse: type: object properties: run: $ref: '#/components/schemas/WarmLeadRun' credits_charged: type: integer minimum: 0 idempotent: type: boolean required: - run - credits_charged additionalProperties: false WarmLeadRun: type: object properties: id: type: string format: uuid status: type: string enum: - queued - signals_running - contacts_running - drafting_running - completed - blocked - failed domain: type: string normalized_domain: type: string credits_charged: type: integer minimum: 0 blocked_reason: type: - string - 'null' error_message: type: - string - 'null' result: anyOf: - $ref: '#/components/schemas/WarmLeadResult' - type: 'null' provider_counters: type: object additionalProperties: true created_at: type: string format: date-time updated_at: type: string format: date-time completed_at: type: - string - 'null' format: date-time required: - id - status - domain - normalized_domain - credits_charged - created_at - updated_at additionalProperties: false ErrorResponse: type: object properties: error: type: string message: type: string required: - error additionalProperties: true PaymentRequiredResponse: allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object properties: credits_required: type: number breakdown: type: object additionalProperties: type: number topup: type: object description: Recommended credit top-up package with billing URL properties: recommended_package_credits: type: integer description: Credits in the recommended package recommended_package_price_usd: type: number description: Price of the recommended package in USD topup_url: type: string format: uri description: URL to billing page with package pre-selected required: - recommended_package_credits - recommended_package_price_usd - topup_url required: - credits_required - topup additionalProperties: true RateLimitErrorResponse: allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object properties: retry_after: type: integer required: - retry_after WarmLeadResult: type: object description: >- Canonical JSON warm-lead result. CSV and XLSX exports are flattened projections of this object. properties: runId: type: string format: uuid status: type: string enum: - completed - blocked - failed account: type: object additionalProperties: true signals: type: array items: type: object additionalProperties: true contacts: type: array maxItems: 3 items: type: object additionalProperties: true scoring: type: object additionalProperties: true drafts: type: array maxItems: 3 items: type: object additionalProperties: true policy: type: object additionalProperties: true counters: type: object additionalProperties: true exportRows: type: array items: type: object additionalProperties: true exportUrls: type: object additionalProperties: type: string required: - runId - status - account - signals - contacts - scoring - drafts - policy - counters additionalProperties: true responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' PaymentRequired: description: Insufficient credits content: application/json: schema: $ref: '#/components/schemas/PaymentRequiredResponse' Conflict: description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' TooManyRequests: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponse' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: AgentApiKey: type: http scheme: bearer description: Bearer citedy_agent_* key ````