GoodLeads Admin API

openapi: 3.2.0
info:
  title: Formation GTM Admin API
  description: GoodLeads Formation Data Platform — scored, enriched, campaign-ready leads.
  version: 0.1.0
tags:
- name: Admin
paths:
  /api/v1/admin/partner-access:
    post:
      tags:
      - Admin
      summary: Create Partner Access
      description: 'Mint a 72-hour magic link that delivers the read-only dashboard key.


        Admin-only (the page carries a live credential). Returns the presigned URL

        for the admin to send from their own email/text — nothing is dispatched.'
      operationId: create_partner_access_api_v1_admin_partner_access_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerAccessRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerAccessResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/admin/replay-tracerfy:
    post:
      tags:
      - Admin
      summary: Replay Tracerfy Start
      description: 'Launch a replay job and return immediately.


        The work runs in the background; the report lands in S3 at

        `s3:///enrichment/_replay/tracerfy/reports/.json`.

        Poll `GET /admin/replay-tracerfy/{report_id}` for completion.'
      operationId: replay_tracerfy_start_api_v1_admin_replay_tracerfy_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplayTracerfyRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplayTracerfyAccepted'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/admin/replay-tracerfy/{report_id}:
    get:
      tags:
      - Admin
      summary: Replay Tracerfy Status
      description: Read the current state of a replay job from S3.
      operationId: replay_tracerfy_status_api_v1_admin_replay_tracerfy__report_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: report_id
        in: path
        required: true
        schema:
          type: string
          title: Report Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplayTracerfyReport'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/llm-audit/summary:
    get:
      tags:
      - Admin
      summary: Llm Audit Summary
      description: 'Aggregate repeat-spend view over the last `days` of LLM calls.


        Read-only, admin-key gated; runs on the read session (replica when one is

        configured). Out-of-range `days` is a 422, not a silent reinterpretation.'
      operationId: llm_audit_summary_api_v1_admin_llm_audit_summary_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 365
          minimum: 1
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LlmAuditSummary'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/suppressions:
    get:
      tags:
      - Admin
      summary: List Suppressions
      operationId: list_suppressions_api_v1_admin_suppressions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  additionalProperties: true
                  type: object
                type: array
                title: Response List Suppressions Api V1 Admin Suppressions Get
      security:
      - APIKeyHeader: []
    post:
      tags:
      - Admin
      summary: Add Suppression
      description: Stop selling this person on every path, now; returns who already holds them.
      operationId: add_suppression_api_v1_admin_suppressions_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuppressionRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Add Suppression Api V1 Admin Suppressions Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/admin/suppressions/{contact_ref}/holders:
    get:
      tags:
      - Admin
      summary: Suppression Holders
      description: 'Customers and partner CRMs that already hold a record for this person: the notification list.'
      operationId: suppression_holders_api_v1_admin_suppressions__contact_ref__holders_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: contact_ref
        in: path
        required: true
        schema:
          type: string
          title: Contact Ref
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Suppression Holders Api V1 Admin Suppressions  Contact Ref  Holders Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/api-keys:
    post:
      tags:
      - Admin
      summary: Issue Key
      operationId: issue_key_api_v1_admin_api_keys_post
      security:
      - APIKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueKeyRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Issue Key Api V1 Admin Api Keys Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Admin
      summary: List Keys
      operationId: list_keys_api_v1_admin_api_keys_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
          minLength: 3
          maxLength: 320
          title: Email
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Keys Api V1 Admin Api Keys Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/api-keys/{key_id}/revoke:
    post:
      tags:
      - Admin
      summary: Revoke Key
      operationId: revoke_key_api_v1_admin_api_keys__key_id__revoke_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/backend__routers__admin_api_keys__RevokeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Revoke Key Api V1 Admin Api Keys  Key Id  Revoke Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    backend__routers__admin_api_keys__RevokeRequest:
      properties:
        reason:
          type: string
          maxLength: 500
          minLength: 1
          title: Reason
      additionalProperties: false
      type: object
      required:
      - reason
      title: RevokeRequest
    ReplayTracerfyRequest:
      properties:
        queue_ids:
          items:
            type: integer
          type: array
          maxItems: 200
          minItems: 1
          title: Queue Ids
        states:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: States
          description: States to load into the matcher index. Defaults to all live states (the pipeline.config registry).
        dry_run:
          type: boolean
          title: Dry Run
          description: When True, parse + match but don't commit any writes
          default: false
      type: object
      required:
      - queue_ids
      title: ReplayTracerfyRequest
    PartnerAccessResponse:
      properties:
        url:
          type: string
          title: Url
        expires_at:
          type: string
          title: Expires At
        partner_name:
          type: string
          title: Partner Name
      type: object
      required:
      - url
      - expires_at
      - partner_name
      title: PartnerAccessResponse
    PartnerAccessRequest:
      properties:
        partner_name:
          type: string
          maxLength: 80
          minLength: 1
          title: Partner Name
          description: Shown on the welcome page greeting
      type: object
      required:
      - partner_name
      title: PartnerAccessRequest
    SuppressionRequest:
      properties:
        contact_ref:
          type: string
          title: Contact Ref
          description: The person's GLC, e.g. GLC-00042
        request_type:
          type: string
          enum:
          - do_not_sell
          - delete
          title: Request Type
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
          description: An email the requester gave, when not the one on file
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
          description: A phone the requester gave, when not the one on file
        received_on:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Received On
          description: The day the request arrived (the deadline clock)
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
      type: object
      required:
      - contact_ref
      - request_type
      title: SuppressionRequest
    IssueKeyRequest:
      properties:
        email:
          type: string
          maxLength: 320
          minLength: 3
          title: Email
        declared_use:
          type: string
          maxLength: 64
          title: Declared Use
          description: 'One of: b2b_sales_outreach, b2b_marketing, crm_enrichment, market_research, platform_integration'
        mode:
          type: string
          maxLength: 8
          title: Mode
          default: test
        label:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Label
        company:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Company
        scopes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Scopes
          description: 'Default: every scope.'
        rate_limit_per_min:
          anyOf:
          - type: integer
            maximum: 10000.0
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Rate Limit Per Min
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
      additionalProperties: false
      type: object
      required:
      - email
      - declared_use
      title: IssueKeyRequest
    ReplayTracerfyAccepted:
      properties:
        report_id:
          type: string
          title: Report Id
        status_url:
          type: string
          title: Status Url
        state:
          type: string
          title: State
          default: running
      type: object
      required:
      - report_id
      - status_url
      title: ReplayTracerfyAccepted
    ReplayTracerfyReport:
      properties:
        report_id:
          type: string
          title: Report Id
        state:
          type: string
          title: State
        started_at:
          type: string
          title: Started At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        aggregate:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Aggregate
        per_queue:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Per Queue
        state_coverage:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: State Coverage
        matcher_stats:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Matcher Stats
      type: object
      required:
      - report_id
      - state
      - started_at
      title: ReplayTracerfyReport
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LlmAuditSummary:
      properties:
        window_days:
          type: integer
          title: Window Days
        total_calls:
          type: integer
          title: Total Calls
        unique_prompts:
          type: integer
          title: Unique Prompts
          description: Distinct prompt hashes across ALL agents (a true global distinct, not a per-agent sum)
        repeat_calls:
          type: integer
          title: Repeat Calls
        repeat_rate:
          type: number
          title: Repeat Rate
        agents:
          items:
            $ref: '#/components/schemas/LlmAuditAgentSummary'
          type: array
          title: Agents
      type: object
      required:
      - window_days
      - total_calls
      - unique_prompts
      - repeat_calls
      - repeat_rate
      - agents
      title: LlmAuditSummary
    LlmAuditAgentSummary:
      properties:
        agent_id:
          type: string
          title: Agent Id
        calls:
          type: integer
          title: Calls
        unique_prompts:
          type: integer
          title: Unique Prompts
        repeat_calls:
          type: integer
          title: Repeat Calls
          description: 'calls - unique_prompts: the re-paid work a harvest store would answer for free'
        repeat_rate:
          type: number
          title: Repeat Rate
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        errors:
          type: integer
          title: Errors
      type: object
      required:
      - agent_id
      - calls
      - unique_prompts
      - repeat_calls
      - repeat_rate
      - input_tokens
      - output_tokens
      - errors
      title: LlmAuditAgentSummary
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key