openapi: 3.2.0
info:
  contact:
    email: support@gatiflow.io
    name: GatiFlow Support
    url: https://gatiflow.io/api-docs
  description: Customer-facing GatiFlow Intelligence API.
  license:
    name: Proprietary
    url: https://gatiflow.io/terms
  termsOfService: https://gatiflow.io/terms
  title: GatiFlow SaaS API — Public Intelligence API
  version: 2.3.0
servers:
- description: Production
  url: https://api.gatiflow.io
tags:
- name: intelligence
paths:
  /api/v1/intelligence/report:
    get:
      description: 'Runs a report for the calling organization over the most recent collection cycle and returns it as JSON. Every signal carries its sources, a mention count and a confidence score, and on plans that include evidence, the raw evidence behind that count.


        Signal caps per plan: Starter 15, Pro 40, Business 100. An expired trial falls back to a watermarked 3-signal preview with confidence and evidence removed.


        Results are filtered to the topics configured on the organization profile. A successful call consumes one unit of the daily quota; a failed generation refunds it. If the underlying data is older than 24 hours the endpoint returns 503 with a Retry-After header rather than serving stale intelligence.


        The schema_version query parameter selects the shape of the contract block, not the version of the payload: 1.1 and 1.2 both return the full contract with capabilities and limits, while the default 1.0 returns the compact one. The response reports the schema it actually is, at the top level and inside the contract, and the two always agree.'
      operationId: report_api_v1_intelligence_report_get
      parameters:
      - in: query
        name: schema_version
        required: false
        schema:
          default: '1.0'
          pattern: ^(1\.0|1\.1|1\.2)$
          title: Schema Version
          type: string
      - in: header
        name: X-API-Key
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          content:
            application/json:
              examples:
                pro:
                  description: 'Same shape as Starter with the Pro caps: up to 40 signals and CSV export.'
                  summary: Pro plan, full contract (schema 1.2)
                  value:
                    analytics:
                      market_overview:
                        average_score: 84.0
                        top_score: 84
                        total_profiles_analyzed: 1
                      role_distribution:
                        Senior Backend: 1
                      seniority_distribution:
                        junior_65_69: 0
                        leadership_90_99: 0
                        mid_70_79: 0
                        senior_80_89: 1
                      seniority_levels:
                        senior: 1
                      stack_distribution:
                        rust: 1
                      strategic_insights: []
                    client_info:
                      client_name: Acme Capital
                      daily_limit: 100
                      org_name: Acme Capital
                      plan: Pro
                      subscription_status: active
                      used_today: 3
                    contract:
                      capabilities:
                        exports:
                        - csv
                        org_briefing: false
                        show_confidence: true
                        show_evidence: true
                      limits:
                        max_signals: 40
                        max_talents: 30
                        max_trends: 40
                      plan_level: Pro
                      report_type: Market & Talent Intelligence
                      schema_version: '1.2'
                    generated_at: '2026-09-03T06:00:11.482913+00:00'
                    metadata:
                      ai_generated:
                        applies_to:
                        - executive_summary.narrative
                        model: Anthropic Claude (Sonnet)
                        purpose: Convert structured signals into human-readable narrative; numeric claims fact-checked.
                      confidentiality: B2B Internal / Client Use
                      generated_at: '2026-09-03T06:00:11.482913+00:00'
                      product: GatiFlow Intelligence
                      report_version: '1.2'
                    org_id: 3f2a9c14-0b7e-4d21-9a56-8c1d4e7b0f33
                    plan: pro
                    schema_version: '1.2'
                    score:
                      overall_confidence: 0.86
                      signal_count: 38
                    sections:
                      executive_summary:
                        narrative: ''
                        overall_confidence: 0.86
                        summary: 'Full analysis of 38 signals from 9 of 13 sources. Top topics: rust, inference, postgres. 1 talent signals identified.'
                        title: Market & Talent Intelligence Overview
                      hiring_signals:
                        count: 1
                        data:
                        - category: hiring_signal
                          confidence: 0.77
                          detail: Backend openings up week over week
                          evidence:
                            company_size: 50-200
                            trend: expanding
                          source: hiring
                          timestamp: '2026-09-03T06:00:11.482913+00:00'
                          title: Series B infrastructure hiring
                        title: Hiring & Opportunity Signals
                      market_trends:
                        count: 1
                        data:
                        - category: market_trend
                          confidence: 0.91
                          detail: 'Strength: high | Mentions: 16'
                          evidence:
                            mentions: 16
                            metric: mentions
                            sources:
                            - hackernews
                            - arxiv
                            title: rust
                          source: hackernews,arxiv
                          timestamp: '2026-09-03T06:00:11.482913+00:00'
                          title: rust
                          url: https://news.ycombinator.com/item?id=41234567
                        title: Market Intelligence Signals
                      talent_signals:
                        count: 1
                        data:
                        - category: talent
                          confidence: 0.82
                          detail: Senior Rust engineer, 8 public repositories this quarter
                          evidence:
                            role: Senior Backend
                            seniority: senior
                            stack:
                            - rust
                          source: github
                          timestamp: '2026-09-03T06:00:11.482913+00:00'
                          title: '@octodev'
                          url: https://github.com/octodev
                        title: Talent Intelligence Signals
                    trend_analysis:
                      analysis_timestamp: '2026-09-03T06:00:11.482913+00:00'
                      declining: []
                      emerging: []
                      engine: v3
                      hot_memory: {}
                      silent_but_rising: []
                      snapshot_count: 27
                      spikes: []
                      status: ok
                      summary: 'Fastest growing: rust (+42.9% vs previous period)'
                      tracking_stats:
                        longest_tracked_days: 14
                        signals_current: 38
                        signals_tracked_7d: 12
                      velocity:
                      - baseline_metric: 11.2
                        category: market_trend
                        change_pct: 42.9
                        current_confidence: 0.91
                        current_mentions: 16
                        current_metric: 16.0
                        current_sources: 2
                        metric_kind: mentions
                        metric_trend: rising
                        presence: active
                        sources_list:
                        - arxiv
                        - hackernews
                        status: tracked
                        topic: rust
                        tracked_days: 9
                      weeks_of_data: 2
                starter:
                  description: Evidence and confidence are present. Signals are capped at 15 and exports are not available.
                  summary: Starter plan, full contract (schema 1.2)
                  value:
                    analytics:
                      market_overview:
                        average_score: 84.0
                        top_score: 84
                        total_profiles_analyzed: 1
                      role_distribution:
                        Senior Backend: 1
                      seniority_distribution:
                        junior_65_69: 0
                        leadership_90_99: 0
                        mid_70_79: 0
                        senior_80_89: 1
                      seniority_levels:
                        senior: 1
                      stack_distribution:
                        rust: 1
                      strategic_insights: []
                    client_info:
                      client_name: Acme Capital
                      daily_limit: 100
                      org_name: Acme Capital
                      plan: Starter
                      subscription_status: active
                      used_today: 3
                    contract:
                      capabilities:
                        exports: []
                        org_briefing: false
                        show_confidence: true
                        show_evidence: true
                      limits:
                        max_signals: 15
                        max_talents: 8
                        max_trends: 15
                      plan_level: Starter
                      report_type: Market & Talent Intelligence
                      schema_version: '1.2'
                    generated_at: '2026-09-03T06:00:11.482913+00:00'
                    metadata:
                      ai_generated:
                        applies_to:
                        - executive_summary.narrative
                        model: Anthropic Claude (Sonnet)
                        purpose: Convert structured signals into human-readable narrative; numeric claims fact-checked.
                      confidentiality: B2B Internal / Client Use
                      generated_at: '2026-09-03T06:00:11.482913+00:00'
                      product: GatiFlow Intelligence
                      report_version: '1.2'
                    org_id: 3f2a9c14-0b7e-4d21-9a56-8c1d4e7b0f33
                    plan: starter
                    schema_version: '1.2'
                    score:
                      overall_confidence: 0.86
                      signal_count: 38
                    sections:
                      executive_summary:
                        narrative: ''
                        overall_confidence: 0.86
                        summary: 'Full analysis of 38 signals from 9 of 13 sources. Top topics: rust, inference, postgres. 1 talent signals identified.'
                        title: Market & Talent Intelligence Overview
                      hiring_signals:
                        count: 1
                        data:
                        - category: hiring_signal
                          confidence: 0.77
                          detail: Backend openings up week over week
                          evidence:
                            company_size: 50-200
                            trend: expanding
                          source: hiring
                          timestamp: '2026-09-03T06:00:11.482913+00:00'
                          title: Series B infrastructure hiring
                        title: Hiring & Opportunity Signals
                      market_trends:
                        count: 1
                        data:
                        - category: market_trend
                          confidence: 0.91
                          detail: 'Strength: high | Mentions: 16'
                          evidence:
                            mentions: 16
                            metric: mentions
                            sources:
                            - hackernews
                            - arxiv
                            title: rust
                          source: hackernews,arxiv
                          timestamp: '2026-09-03T06:00:11.482913+00:00'
                          title: rust
                          url: https://news.ycombinator.com/item?id=41234567
                        title: Market Intelligence Signals
                      talent_signals:
                        count: 1
                        data:
                        - category: talent
                          confidence: 0.82
                          detail: Senior Rust engineer, 8 public repositories this quarter
                          evidence:
                            role: Senior Backend
                            seniority: senior
                            stack:
                            - rust
                          source: github
                          timestamp: '2026-09-03T06:00:11.482913+00:00'
                          title: '@octodev'
                          url: https://github.com/octodev
                        title: Talent Intelligence Signals
                    trend_analysis:
                      analysis_timestamp: '2026-09-03T06:00:11.482913+00:00'
                      declining: []
                      emerging: []
                      engine: v3
                      hot_memory: {}
                      silent_but_rising: []
                      snapshot_count: 27
                      spikes: []
                      status: ok
                      summary: 'Fastest growing: rust (+42.9% vs previous period)'
                      tracking_stats:
                        longest_tracked_days: 14
                        signals_current: 38
                        signals_tracked_7d: 12
                      velocity:
                      - baseline_metric: 11.2
                        category: market_trend
                        change_pct: 42.9
                        current_confidence: 0.91
                        current_mentions: 16
                        current_metric: 16.0
                        current_sources: 2
                        metric_kind: mentions
                        metric_trend: rising
                        presence: active
                        sources_list:
                        - arxiv
                        - hackernews
                        status: tracked
                        topic: rust
                        tracked_days: 9
                      weeks_of_data: 2
              schema:
                $ref: '#/components/schemas/IntelligenceReport'
          description: Intelligence report for the calling organization.
          headers:
            X-DailyQuota-Limit:
              description: Calls the plan allows per day.
              schema:
                minimum: 0
                type: integer
            X-DailyQuota-Remaining:
              description: Calls left in today's quota.
              schema:
                minimum: 0
                type: integer
            X-RateLimit-Limit:
              description: Requests the plan allows in one rate-limit window.
              schema:
                minimum: 0
                type: integer
            X-RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                minimum: 0
                type: integer
            X-RateLimit-Reset-Seconds:
              description: Length of the sliding window, in seconds. A request refused with 429 succeeds once this many seconds have passed.
              schema:
                minimum: 0
                type: integer
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The X-API-Key header is missing, or the key is unknown, revoked or expired.
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The organization has no subscription, or the subscription is not active.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The organization is inactive, its owner's email address is still unverified after the three-day grace period, or the key lacks the intelligence:read scope.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: A parameter is missing, malformed or out of range. error.details lists each problem.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'The plan''s per-minute rate limit or daily quota is exhausted. error.message says which: Rate limit exceeded, or Daily quota exceeded.'
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StaleDataError'
          description: The underlying data is older than 24 hours. Sent with a Retry-After header, in seconds.
          headers:
            Retry-After:
              description: Seconds to wait before asking again.
              schema:
                minimum: 0
                type: integer
      security:
      - ApiKeyAuth: []
      summary: Generate an intelligence report
      tags:
      - intelligence
  /api/v1/intelligence/report-history:
    get:
      description: 'Lists the report snapshots retained for this organization, newest first. Snapshots are written by the collection cycle, not by report calls, so this list reflects what was actually collected. Each entry carries a snapshot_id in the YYYYMMDDTHHmm format, which is what GET /intelligence/report/at/{snapshot_id} expects.


        Retention follows the plan: Starter keeps 7 days, Pro keeps 90 days, Business keeps 365 days. An expired trial retains nothing and receives an empty list.


        This endpoint returns metadata only and does not consume daily quota, but it does count against the plan per-minute rate limit.'
      operationId: report_history_list_api_v1_intelligence_report_history_get
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 50
          minimum: 1
          title: Limit
          type: integer
      - in: header
        name: X-API-Key
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          content:
            application/json:
              examples:
                empty:
                  description: Returned for an expired trial, which retains nothing.
                  summary: No retained snapshots
                  value:
                    count: 0
                    plan: free
                    retention_days: 0
                    snapshots: []
                pro:
                  summary: Two snapshots on a Pro key
                  value:
                    count: 2
                    plan: pro
                    retention_days: 90
                    snapshots:
                    - generated_at: '2026-09-03T06:00:11.482913+00:00'
                      signal_count: 38
                      snapshot_id: 20260903T0600
                    - generated_at: '2026-09-02T06:00:09.117204+00:00'
                      signal_count: 35
                      snapshot_id: 20260902T0600
              schema:
                $ref: '#/components/schemas/ReportHistory'
          description: Snapshot metadata for this organization, newest first.
          headers:
            X-RateLimit-Limit:
              description: Requests the plan allows in one rate-limit window.
              schema:
                minimum: 0
                type: integer
            X-RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                minimum: 0
                type: integer
            X-RateLimit-Reset-Seconds:
              description: Length of the sliding window, in seconds. A request refused with 429 succeeds once this many seconds have passed.
              schema:
                minimum: 0
                type: integer
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The X-API-Key header is missing, or the key is unknown, revoked or expired.
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The organization has no subscription, or the subscription is not active.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The organization is inactive, its owner's email address is still unverified after the three-day grace period, or the key lacks the intelligence:read scope.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: A parameter is missing, malformed or out of range. error.details lists each problem.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'The plan''s per-minute rate limit is exhausted: error.message is Rate limit exceeded.'
      security:
      - ApiKeyAuth: []
      summary: List retained report snapshots
      tags:
      - intelligence
  /api/v1/intelligence/report/at/{snapshot_id}:
    get:
      description: 'Returns a report that was archived by an earlier collection cycle, in the same shape as GET /intelligence/report. Use GET /intelligence/report-history to discover the ids that exist.


        snapshot_id uses the YYYYMMDDTHHmm format, for example 20260509T1225. An id in any other shape returns 400 without a lookup.


        Availability follows the plan retention window: Starter keeps 7 days, Pro keeps 90 days, Business keeps 365 days. A plan with no history receives 403, and an id outside the window returns 404.


        Reading an archived snapshot does not consume daily quota, but it does count against the plan per-minute rate limit, including requests with an invalid id.'
      operationId: report_at_snapshot_api_v1_intelligence_report_at__snapshot_id__get
      parameters:
      - in: path
        name: snapshot_id
        required: true
        schema:
          title: Snapshot Id
          type: string
      - in: header
        name: X-API-Key
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          content:
            application/json:
              examples:
                pro:
                  description: The stored report, in the same shape GET /intelligence/report returns.
                  summary: One archived snapshot
                  value:
                    analytics:
                      market_overview:
                        average_score: 84.0
                        top_score: 84
                        total_profiles_analyzed: 1
                      role_distribution:
                        Senior Backend: 1
                      seniority_distribution:
                        junior_65_69: 0
                        leadership_90_99: 0
                        mid_70_79: 0
                        senior_80_89: 1
                      seniority_levels:
                        senior: 1
                      stack_distribution:
                        rust: 1
                      strategic_insights: []
                    client_info:
                      client_name: Acme Capital
                      daily_limit: 100
                      org_name: Acme Capital
                      plan: Pro
                      subscription_status: active
                      used_today: 3
                    contract:
                      capabilities:
                        exports:
                        - csv
                        org_briefing: false
                        show_confidence: true
                        show_evidence: true
                      limits:
                        max_signals: 40
                        max_talents: 30
                        max_trends: 40
                      plan_level: Pro
                      report_type: Market & Talent Intelligence
                      schema_version: '1.2'
                    generated_at: '2026-09-03T06:00:11.482913+00:00'
                    metadata:
                      ai_generated:
                        applies_to:
                        - executive_summary.narrative
                        model: Anthropic Claude (Sonnet)
                        purpose: Convert structured signals into human-readable narrative; numeric claims fact-checked.
                      confidentiality: B2B Internal / Client Use
                      generated_at: '2026-09-03T06:00:11.482913+00:00'
                      product: GatiFlow Intelligence
                      report_version: '1.2'
                    org_id: 3f2a9c14-0b7e-4d21-9a56-8c1d4e7b0f33
                    plan: pro
                    schema_version: '1.2'
                    score:
                      overall_confidence: 0.86
                      signal_count: 38
                    sections:
                      executive_summary:
                        narrative: ''
                        overall_confidence: 0.86
                        summary: 'Full analysis of 38 signals from 9 of 13 sources. Top topics: rust, inference, postgres. 1 talent signals identified.'
                        title: Market & Talent Intelligence Overview
                      hiring_signals:
                        count: 1
                        data:
                        - category: hiring_signal
                          confidence: 0.77
                          detail: Backend openings up week over week
                          evidence:
                            company_size: 50-200
                            trend: expanding
                          source: hiring
                          timestamp: '2026-09-03T06:00:11.482913+00:00'
                          title: Series B infrastructure hiring
                        title: Hiring & Opportunity Signals
                      market_trends:
                        count: 1
                        data:
                        - category: market_trend
                          confidence: 0.91
                          detail: 'Strength: high | Mentions: 16'
                          evidence:
                            mentions: 16
                            metric: mentions
                            sources:
                            - hackernews
                            - arxiv
                            title: rust
                          source: hackernews,arxiv
                          timestamp: '2026-09-03T06:00:11.482913+00:00'
                          title: rust
                          url: https://news.ycombinator.com/item?id=41234567
                        title: Market Intelligence Signals
                      talent_signals:
                        count: 1
                        data:
                        - category: talent
                          confidence: 0.82
                          detail: Senior Rust engineer, 8 public repositories this quarter
                          evidence:
                            role: Senior Backend
                            seniority: senior
                            stack:
                            - rust
                          source: github
                          timestamp: '2026-09-03T06:00:11.482913+00:00'
                          title: '@octodev'
                          url: https://github.com/octodev
                        title: Talent Intelligence Signals
                    trend_analysis:
                      analysis_timestamp: '2026-09-03T06:00:11.482913+00:00'
                      declining: []
                      emerging: []
                      engine: v3
                      hot_memory: {}
                      silent_but_rising: []
                      snapshot_count: 27
                      spikes: []
                      status: ok
                      summary: 'Fastest growing: rust (+42.9% vs previous period)'
                      tracking_stats:
                        longest_tracked_days: 14
                        signals_current: 38
                        signals_tracked_7d: 12
                      velocity:
                      - baseline_metric: 11.2
                        category: market_trend
                        change_pct: 42.9
                        current_confidence: 0.91
                        current_mentions: 16
                        current_metric: 16.0
                        current_sources: 2
                        metric_kind: mentions
                        metric_trend: rising
                        presence: active
                        sources_list:
                        - arxiv
                        - hackernews
                        status: tracked
                        topic: rust
                        tracked_days: 9
                      weeks_of_data: 2
              schema:
                $ref: '#/components/schemas/IntelligenceReport'
          description: The archived report for the requested snapshot_id.
          headers:
            X-RateLimit-Limit:
              description: Requests the plan allows in one rate-limit window.
              schema:
                minimum: 0
                type: integer
            X-RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                minimum: 0
                type: integer
            X-RateLimit-Reset-Seconds:
              description: Length of the sliding window, in seconds. A request refused with 429 succeeds once this many seconds have passed.
              schema:
                minimum: 0
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: snapshot_id is not in the YYYYMMDDTHHmm format.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The X-API-Key header is missing, or the key is unknown, revoked or expired.
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The organization has no subscription, or the subscription is not active.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The plan does not retain history, the organization is inactive, its owner's email address is still unverified after the three-day grace period, or the key lacks the intelligence:read scope.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: No snapshot with that id inside the plan retention window.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: A parameter is missing, malformed or out of range. error.details lists each problem.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'The plan''s per-minute rate limit is exhausted: error.message is Rate limit exceeded.'
      security:
      - ApiKeyAuth: []
      summary: Retrieve an archived report snapshot
      tags:
      - intelligence
  /api/v1/intelligence/report/export:
    get:
      description: 'Returns the same report as GET /intelligence/report, serialized to a downloadable file instead of JSON. The response body is the file itself, with a Content-Disposition attachment header and a dated filename.


        Export formats follow the plan: Starter has none and receives 403, Pro can export CSV, Business can export CSV and PDF.


        A successful export consumes one unit of the daily quota, the same as a report call. If the underlying data is older than 24 hours the endpoint returns 503 with a Retry-After header.'
      operationId: export_report_api_v1_intelligence_report_export_get
      parameters:
      - in: query
        name: format
        required: false
        schema:
          default: csv
          pattern: ^(csv|pdf)$
          title: Format
          type: string
      - in: header
        name: X-API-Key
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          content:
            application/pdf:
              schema:
                format: binary
                type: string
            text/csv:
              example: 'section,title,detail,source,category,confidence,url,timestamp

                market_trends,rust,Strength: high | Mentions: 16,"hackernews,arxiv",market_trend,0.91,https://news.ycombinator.com/item?id=41234567,2026-09-03T06:00:11.482913+00:00

                talent_signals,''@octodev,"Senior Rust engineer, 8 public repositories this quarter",github,talent,0.82,https://github.com/octodev,2026-09-03T06:00:11.482913+00:00

                hiring_signals,Series B infrastructure hiring,Backend openings up week over week,hiring,hiring_signal,0.77,,2026-09-03T06:00:11.482913+00:00

                '
              schema:
                format: binary
                type: string
          description: The report as a file attachment. Content-Type follows the requested format.
          headers:
            X-DailyQuota-Limit:
              description: Calls the plan allows per day.
              schema:
                minimum: 0
                type: integer
            X-DailyQuota-Remaining:
              description: Calls left in today's quota.
              schema:
                minimum: 0
                type: integer
            X-RateLimit-Limit:
              description: Requests the plan allows in one rate-limit window.
              schema:
                minimum: 0
                type: integer
            X-RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                minimum: 0
                type: integer
            X-RateLimit-Reset-Seconds:
              description: Length of the sliding window, in seconds. A request refused with 429 succeeds once this many seconds have passed.
              schema:
                minimum: 0
                type: integer
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The X-API-Key header is missing, or the key is unknown, revoked or expired.
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The organization has no subscription, or the subscription is not active.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The plan does not include the requested export format, the organization is inactive, its owner's email address is still unverified after the three-day grace period, or the key lacks the intelligence:read scope.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: A parameter is missing, malformed or out of range. error.details lists each problem.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'The plan''s per-minute rate limit or daily quota is exhausted. error.message says which: Rate limit exceeded, or Daily quota exceeded.'
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StaleDataError'
          description: The underlying data is older than 24 hours. Sent with a Retry-After header, in seconds.
          headers:
            Retry-After:
              description: Seconds to wait before asking again.
              schema:
                minimum: 0
                type: integer
      security:
      - ApiKeyAuth: []
      summary: Export the report as a file
      tags:
      - intelligence
components:
  schemas:
    StaleDataError:
      description: 'The 503 an operation returns rather than serve intelligence older than

        its freshness ceiling. The same envelope as every error, with a structured

        ``error.message``, sent with a ``Retry-After`` header.'
      properties:
        error:
          $ref: '#/components/schemas/StaleDataErrorDetail'
        metadata:
          $ref: '#/components/schemas/ErrorMetadata'
        status:
          const: error
          title: Status
          type: string
      required:
      - status
      - error
      - metadata
      title: StaleDataError
      type: object
    ErrorDetail:
      description: What went wrong, and the id to quote when asking about it.
      properties:
        code:
          description: NOT_FOUND for a 404, VALIDATION_ERROR for a 422, HTTP_ERROR for every other refusal.
          enum:
          - HTTP_ERROR
          - NOT_FOUND
          - VALIDATION_ERROR
          - INTERNAL_ERROR
          title: Code
          type: string
        details:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              $ref: '#/components/schemas/ValidationIssue'
            type: array
          description: The list of problems on a 422; an empty object otherwise.
          title: Details
        http_status:
          title: Http Status
          type: integer
        message:
          description: Why the request was refused, in plain words.
          title: Message
          type: string
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          description: Also sent as the X-Request-ID response header.
          title: Request Id
      required:
      - message
      - code
      - http_status
      - request_id
      - details
      title: ErrorDetail
      type: object
    ErrorMetadata:
      properties:
        provider:
          title: Provider
          type: string
        timestamp:
          format: date-time
          title: Timestamp
          type: string
        version:
          title: Version
          type: string
      required:
      - timestamp
      - provider
      - version
      title: ErrorMetadata
      type: object
    StaleDataErrorDetail:
      properties:
        code:
          const: HTTP_ERROR
          title: Code
          type: string
        details:
          additionalProperties: true
          title: Details
          type: object
        http_status:
          const: 503
          title: Http Status
          type: integer
        message:
          $ref: '#/components/schemas/StaleDataDetail'
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
      required:
      - message
      - code
      - http_status
      - request_id
      - details
      title: StaleDataErrorDetail
      type: object
    ErrorResponse:
      description: Every refusal the API returns, whatever its status.
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
        metadata:
          $ref: '#/components/schemas/ErrorMetadata'
        status:
          const: error
          title: Status
          type: string
      required:
      - status
      - error
      - metadata
      title: ErrorResponse
      type: object
    IntelligenceReport:
      description: 'The intelligence report for the calling organization.


        The same shape is served for an archived snapshot, which carries no

        ``client_info`` because it was built by the collection cycle rather than

        for a caller.'
      properties:
        analytics:
          $ref: '#/components/schemas/ReportAnalytics'
        client_info:
          $ref: '#/components/schemas/ClientInfo'
        contract:
          $ref: '#/components/schemas/ReportContract'
        generated_at:
          format: date-time
          title: Generated At
          type: string
        metadata:
          $ref: '#/components/schemas/ReportMetadata'
        org_id:
          title: Org Id
          type: string
        plan:
          title: Plan
          type: string
        schema_version:
          description: The contract shape this payload follows, 1.0 or 1.2.
          title: Schema Version
          type: string
        score:
          $ref: '#/components/schemas/ReportScore'
        sections:
          $ref: '#/components/schemas/ReportSections'
        trend_analysis:
          $ref: '#/components/schemas/TrendAnalysis'
      required:
      - schema_version
      - org_id
      - plan
      - generated_at
      - contract
      - metadata
      - score
      - sections
      - analytics
      title: IntelligenceReport
      type: object
    ReportMetadata:
      description: 'Provenance of the report: when it was built, from what, and how fresh

        the underlying data is.'
      properties:
        ai_generated:
          $ref: '#/components/schemas/AIGeneratedDeclaration'
        collection_health:
          additionalProperties: true
          title: Collection Health
          type: object
        confidentiality:
          title: Confidentiality
          type: string
        corroboration_gate:
          enum:
          - active
          - inactive
          title: Corroboration Gate
          type: string
        data_age_hours:
          title: Data Age Hours
          type: number
        data_collected_at:
          title: Data Collected At
          type: string
        data_source:
          title: Data Source
          type: string
        generated_at:
          format: date-time
          title: Generated At
          type: string
        narrative_credits:
          additionalProperties: true
          title: Narrative Credits
          type: object
        narrative_exhausted:
          title: Narrative Exhausted
          type: boolean
        product:
          title: Product
          type: string
        quality:
          additionalProperties: true
          title: Quality
          type: object
        raw_observations_held:
          title: Raw Observations Held
          type: integer
        relevance_ranking:
          enum:
          - active
          - neutral
          title: Relevance Ranking
          type: string
        report_version:
          title: Report Version
          type: string
        staleness_warning:
          title: Staleness Warning
          type: string
        watermark:
          description: Present on the expired-trial preview only.
          title: Watermark
          type: string
      required:
      - generated_at
      - product
      - report_version
      - confidentiality
      - ai_generated
      title: ReportMetadata
      type: object
    ReportContract:
      description: 'What the plan entitles the caller to. Schema 1.0, the default, carries

        the first three fields only; 1.1 and 1.2 add capabilities and limits.'
      properties:
        capabilities:
          $ref: '#/components/schemas/ReportCapabilities'
        limits:
          $ref: '#/components/schemas/ReportLimits'
        plan_level:
          title: Plan Level
          type: string
        report_type:
          title: Report Type
          type: string
        schema_version:
          title: Schema Version
          type: string
      required:
      - schema_version
      - plan_level
      - report_type
      title: ReportContract
      type: object
    ReportSections:
      description: The report body.
      properties:
        executive_summary:
          $ref: '#/components/schemas/ExecutiveSummary'
        hiring_signals:
          $ref: '#/components/schemas/SignalSection'
        market_trends:
          $ref: '#/components/schemas/SignalSection'
        org_briefing:
          $ref: '#/components/schemas/OrgBriefing'
        talent_signals:
          $ref: '#/components/schemas/SignalSection'
      required:
      - executive_summary
      - market_trends
      - talent_signals
      - hiring_signals
      title: ReportSections
      type: object
    MarketOverview:
      properties:
        average_score:
          title: Average Score
          type: number
        top_score:
          title: Top Score
          type: number
        total_profiles_analyzed:
          title: Total Profiles Analyzed
          type: integer
      required:
      - total_profiles_analyzed
      - average_score
      - top_score
      title: MarketOverview
      type: object
    SnapshotSummary:
      properties:
        generated_at:
          format: date-time
          title: Generated At
          type: string
        signal_count:
          title: Signal Count
          type: integer
        snapshot_id:
          description: YYYYMMDDTHHmm
          pattern: ^\d{8}T\d{4}$
          title: Snapshot Id
          type: string
      required:
      - snapshot_id
      - generated_at
      - signal_count
      title: SnapshotSummary
      type: object
    ReportAnalytics:
      description: Distributions over the talent profiles in the report.
      properties:
        market_overview:
          $ref: '#/components/schemas/MarketOverview'
        role_distribution:
          additionalProperties:
            type: integer
          title: Role Distribution
          type: object
        seniority_distribution:
          additionalProperties:
            type: integer
          description: Profiles per score band.
          title: Seniority Distribution
          type: object
        seniority_levels:
          additionalProperties:
            type: integer
          description: Profiles per seniority label.
          title: Seniority Levels
          type: object
        stack_distribution:
          additionalProperties:
            type: integer
          title: Stack Distribution
          type: object
        strategic_insights:
          items:
            type: string
          title: Strategic Insights
          type: array
      required:
      - market_overview
      - seniority_distribution
      - seniority_levels
      - stack_distribution
      - role_distribution
      - strategic_insights
      title: ReportAnalytics
      type: object
    ReportCapabilities:
      properties:
        exports:
          description: Export formats the plan includes.
          items:
            enum:
            - csv
            - pdf
            type: string
          title: Exports
          type: array
        org_briefing:
          title: Org Briefing
          type: boolean
        show_confidence:
          title: Show Confidence
          type: boolean
        show_evidence:
          title: Show Evidence
          type: boolean
      required:
      - exports
      - show_evidence
      - show_confidence
      - org_briefing
      title: ReportCapabilities
      type: object
    ReportScore:
      description: Aggregate confidence over the signals in the report.
      properties:
        categories:
          additionalProperties:
            type: number
          title: Categories
          type: object
        collection_health:
          additionalProperties: true
          title: Collection Health
          type: object
        confidence_interval:
          additionalProperties: true
          title: Confidence Interval
          type: object
        cross_source_signals:
          title: Cross Source Signals
          type: integer
        overall_confidence:
          maximum: 1.0
          minimum: 0.0
          title: Overall Confidence
          type: number
        signal_count:
          minimum: 0.0
          title: Signal Count
          type: integer
        source_diversity:
          title: Source Diversity
          type: integer
      required:
      - overall_confidence
      - signal_count
      title: ReportScore
      type: object
    ReportLimits:
      properties:
        max_signals:
          title: Max Signals
          type: integer
        max_talents:
          title: Max Talents
          type: integer
        max_trends:
          title: Max Trends
          type: integer
        profile_companies:
          title: Profile Companies
          type: integer
        profile_topics:
          title: Profile Topics
          type: integer
      required:
      - max_trends
      - max_talents
      - max_signals
      title: ReportLimits
      type: object
    ValidationIssue:
      description: One problem with the request, as a 422 lists it in ``error.details``.
      properties:
        ctx:
          description: The constraint that failed, as text.
          title: Ctx
          type: string
        input:
          title: Input
        loc:
          description: Where the problem is, for example ['query', 'limit'].
          items:
            anyOf:
            - type: string
            - type: integer
          title: Loc
          type: array
        msg:
          title: Msg
          type: string
        type:
          title: Type
          type: string
        url:
          title: Url
          type: string
      required:
      - type
      - loc
      - msg
      title: ValidationIssue
      type: object
    ExecutiveSummary:
      description: 'The report overview. ``narrative`` is written by a language model and

        declared as such in ``metadata.ai_generated``.'
      properties:
        narrative:
          title: Narrative
          type: string
        overall_confidence:
          title: Overall Confidence
          type: number
        summary:
          title: Summary
          type: string
        title:
          title: Title
          type: string
      required:
      - title
      - summary
      - narrative
      - overall_confidence
      title: ExecutiveSummary
      type: object
    ClientInfo:
      description: Who the report was built for and how much of today's quota is used.
      properties:
        client_name:
          title: Client Name
          type: string
        daily_limit:
          title: Daily Limit
          type: integer
        org_name:
          title: Org Name
          type: string
        plan:
          title: Plan
          type: string
        subscription_status:
          title: Subscription Status
          type: string
        trial_days_remaining:
          anyOf:
          - type: integer
          - type: 'null'
          title: Trial Days Remaining
        used_today:
          title: Used Today
          type: integer
      required:
      - client_name
      - org_name
      - plan
      - daily_limit
      - used_today
      title: ClientInfo
      type: object
    TrendMovement:
      description: A topic's movement against its own history.
      properties:
        baseline_is_partial:
          title: Baseline Is Partial
          type: boolean
        baseline_metric:
          title: Baseline Metric
          type: number
        category:
          title: Category
          type: string
        change_pct:
          anyOf:
          - type: number
          - type: 'null'
          description: Null when there is no baseline yet.
          title: Change Pct
        current_confidence:
          title: Current Confidence
          type: number
        current_mentions:
          title: Current Mentions
          type: integer
        current_metric:
          title: Current Metric
          type: number
        current_sources:
          title: Current Sources
          type: integer
        last_confidence:
          title: Last Confidence
          type: number
        last_seen_days_ago:
          title: Last Seen Days Ago
          type: integer
        metric_kind:
          title: Metric Kind
          type: string
        metric_trend:
          title: Metric Trend
          type: string
        presence:
          title: Presence
          type: string
        sources_list:
          items:
            type: string
          title: Sources List
          type: array
        spike_magnitude:
          title: Spike Magnitude
          type: number
        status:
          title: Status
          type: string
        topic:
          title: Topic
          type: string
        tracked_days:
          title: Tracked Days
          type: integer
        tracked_days_before:
          title: Tracked Days Before
          type: integer
      required:
      - topic
      - category
      title: TrendMovement
      type: object
    SignalItem:
      description: 'One signal in a report section.


        ``confidence`` and ``evidence`` are present on plans that include them

        and absent on the expired-trial preview.'
      properties:
        category:
          description: Signal category, for example market_trend, research_paper, talent or hiring_signal.
          title: Category
          type: string
        company:
          title: Company
          type: string
        confidence:
          title: Confidence
          type: number
        detail:
          title: Detail
          type: string
        entity_key:
          title: Entity Key
          type: string
        entity_type:
          title: Entity Type
          type: string
        evidence:
          additionalProperties: true
          description: The source metadata behind the counts, as collected.
          title: Evidence
          type: object
        example_headline:
          title: Example Headline
          type: string
        hiring_status:
          title: Hiring Status
          type: string
        relevance:
          title: Relevance
          type: number
        source:
          description: Source ids that observed the signal, comma-separated.
          title: Source
          type: string
        timestamp:
          format: date-time
          title: Timestamp
          type: string
        title:
          title: Title
          type: string
        url:
          title: Url
          type: string
        velocity:
          additionalProperties: true
          description: Week-over-week movement of the signal.
          title: Velocity
          type: object
      required:
      - source
      - title
      - detail
      - category
      - timestamp
      title: SignalItem
      type: object
    StaleDataDetail:
      description: Why a report was refused as too old to serve.
      properties:
        data_age_hours:
          description: Age of the newest collected data, in hours.
          title: Data Age Hours
          type: number
        error:
          const: data_too_stale
          title: Error
          type: string
        message:
          title: Message
          type: string
        threshold_hours:
          description: The ceiling the operation enforces, in hours.
          title: Threshold Hours
          type: number
      required:
      - error
      - message
      - data_age_hours
      - threshold_hours
      title: StaleDataDetail
      type: object
    AIGeneratedDeclaration:
      description: Which parts of the payload a language model wrote.
      properties:
        applies_to:
          items:
            type: string
          title: Applies To
          type: array
        model:
          title: Model
          type: string
        purpose:
          title: Purpose
          type: string
        regulation:
          title: Regulation
          type: string
      required:
      - applies_to
      - model
      - purpose
      title: AIGeneratedDeclaration
      type: object
    TrendAnalysis:
      description: 'Week-over-week movement across the retained collection history.

        ``status`` is ``insufficient_history`` until there is history to compare.'
      properties:
        analysis_timestamp:
          title: Analysis Timestamp
          type: string
        declining:
          items:
            $ref: '#/components/schemas/TrendMovement'
          title: Declining
          type: array
        emerging:
          items:
            $ref: '#/components/schemas/TrendMovement'
          title: Emerging
          type: array
        engine:
          title: Engine
          type: string
        hot_memory:
          additionalProperties: true
          title: Hot Memory
          type: object
        silent_but_rising:
          items:
            $ref: '#/components/schemas/TrendMovement'
          title: Silent But Rising
          type: array
        snapshot_count:
          title: Snapshot Count
          type: integer
        spikes:
          items:
            $ref: '#/components/schemas/TrendMovement'
          title: Spikes
          type: array
        status:
          description: ok, or insufficient_history before any history exists.
          title: Status
          type: string
        summary:
          title: Summary
          type: string
        tracking_stats:
          additionalProperties:
            type: integer
          title: Tracking Stats
          type: object
        velocity:
          items:
            $ref: '#/components/schemas/TrendMovement'
          title: Velocity
          type: array
        weeks_of_data:
          title: Weeks Of Data
          type: number
      required:
      - status
      title: TrendAnalysis
      type: object
    ReportHistory:
      description: Retained snapshots, newest first.
      properties:
        count:
          title: Count
          type: integer
        plan:
          title: Plan
          type: string
        retention_days:
          minimum: 0.0
          title: Retention Days
          type: integer
        snapshots:
          items:
            $ref: '#/components/schemas/SnapshotSummary'
          title: Snapshots
          type: array
      required:
      - snapshots
      - count
      - plan
      - retention_days
      title: ReportHistory
      type: object
    SignalSection:
      description: A section of signals, capped by the plan.
      properties:
        count:
          description: Number of items in data.
          minimum: 0.0
          title: Count
          type: integer
        data:
          items:
            $ref: '#/components/schemas/SignalItem'
          title: Data
          type: array
        title:
          title: Title
          type: string
      required:
      - title
      - count
      - data
      title: SignalSection
      type: object
    OrgBriefing:
      description: 'Business plan only: a paragraph on the organization''s own watchlist.'
      properties:
        narrative:
          title: Narrative
          type: string
        title:
          title: Title
          type: string
      required:
      - title
      - narrative
      title: OrgBriefing
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: API key (prefix gf_) created in Dashboard → API Keys.
      in: header
      name: X-API-Key
      type: apiKey
    SessionBearer:
      bearerFormat: JWT
      description: Web session token issued to the browser at sign-in. It is not part of the public API and cannot be created from an API key; an API key sent to an operation that requires it receives 401.
      scheme: bearer
      type: http
externalDocs:
  description: API documentation
  url: https://gatiflow.io/api-docs
x-provenance:
  generated_from: the running routes (app/api/public_docs.py), compared byte for byte by the test suite
  method: published
  publisher: GatiFlow
  source: https://gatiflow.io/openapi.json