GatiFlow Agent API

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. Authenticate with an API key in the `X-API-Key` header, except on `GET /api/v1/agent/signals`, `GET /api/v1/public/deep-dive`, which need no credential, and on `GET /api/v1/public/weekly-report`, which needs the web-app session bearer instead, so an API key receives 401 there. `GET /api/v1/agent/signals` is paid per call instead, in USDC over the x402 protocol: the first request answers 402 with the price in a `PAYMENT-REQUIRED` header, and the request retried with a signed payment returns the data.


    Rate limits and daily quotas are per plan and per organization: every API key an organization holds draws on the same per-minute limit and the same daily quota. `GET /api/v1/intelligence/report`, `GET /api/v1/intelligence/report/export` return both `X-RateLimit-*` and `X-DailyQuota-*` response headers. `GET /api/v1/intelligence/report-history`, `GET /api/v1/intelligence/report/at/{snapshot_id}` return `X-RateLimit-*` alone: they are rate limited and consume no quota. The remaining operations are metered without reporting a header, so read the figures from `GET /api/v1/usage` or from the plan. The operations that take no credential are capped per caller address instead, and each states its own ceiling.


    ## What people use it for


    **You own an API and want to know what your sector is doing** -- `GET /api/v1/intelligence/report` returns the week filtered to the topics on your organization profile, and its `trend_analysis` block carries the movement (`velocity`, `spikes`, `emerging`, `declining`) instead of a feed you have to read. A daily call is enough: rather than serve intelligence older than 24 hours the endpoint returns 503 with `Retry-After`.


    **You built the product and marketing is the part you are worst at** -- `sections.market_trends` and the `emerging` list in `GET /api/v1/intelligence/report` name the topics your buyers are already reading about, so a post has a subject before it has a deadline. `GET /api/v1/public/deep-dive` returns the preview of the current long-form article with no API key, and the address where the whole article is free to read.


    **You want the signals inside the tools your team already uses** -- `GET /api/v1/intelligence/report/export` returns the same report as a file for a warehouse load or a weekly deck: CSV on Pro, CSV or PDF on Business. `GET /api/v1/intelligence/report-history` and `GET /api/v1/intelligence/report/at/{snapshot_id}` walk the snapshots your plan retains, so a dashboard starts with history instead of one row, and `GET /api/v1/usage` lists the reports and exports a scheduled job fetched with its key, without a second log.'
  license:
    name: Proprietary
    url: https://gatiflow.io/terms
  termsOfService: https://gatiflow.io/terms
  title: GatiFlow SaaS API — Public Agent API
  version: 2.6.1
  x-guidance: 'Agents can buy one call without an account or API key: GET https://api.gatiflow.io/api/v1/agent/signals?topic=<topic> returns the latest collection''s market and hiring signals that mention the topic, each with its sources, mention count and confidence score. Each call costs US$ 0.02 in USDC, paid over x402: the first request answers 402 with a PAYMENT-REQUIRED header (price, network, USDC contract, receiving address); retry the same URL with the signed payment in the PAYMENT-SIGNATURE header. The payment settles only when the call succeeds, so an invalid topic (422), more than 30 requests a minute from one address (429), data older than 24 hours (503) and a topic with no signals in the latest collection (404) cost nothing. A topic is a short technology or market term, 2 to 60 characters of letters, digits, spaces and . + # / -, for example ''Python''. The other operations are not paid per call: GET /api/v1/public/deep-dive needs no credential, and the rest take a GatiFlow API key or the web-app session, as each one''s security states. More: https://gatiflow.io/llms.txt'
servers:
- description: Production
  url: https://api.gatiflow.io
tags:
- description: 'Topic signals for AI agents, paid per call in USDC over x402: no account, no API key. The first request returns 402 with the price; the retried, paid request returns the signals.'
  name: Agent
paths:
  /api/v1/agent/signals:
    get:
      description: 'The latest collection''s market and hiring signals that mention one topic, each with its sources, mention count and confidence score. No authentication is required: there is no account or API key. Each call is paid instead, in USDC over the x402 protocol. The first request returns HTTP 402 with a PAYMENT-REQUIRED header stating the price, the network and the receiving address; the request retried with a signed payment in the PAYMENT-SIGNATURE header returns the signals and a PAYMENT-RESPONSE receipt. The payment settles only when the call succeeds: an invalid topic (422), the per-address limit of 30 requests a minute (429), stale data (503) and a topic with no signals in the latest collection (404) are not charged. Talent signals and evidence fields that name a person are not included.'
      operationId: agent_signals_api_v1_agent_signals_get
      parameters:
      - description: Topic to look up, e.g. 'Python'.
        in: query
        name: topic
        required: true
        schema:
          description: Topic to look up, e.g. 'Python'.
          maxLength: 60
          minLength: 2
          pattern: ^[A-Za-z0-9][A-Za-z0-9 .+#/-]*$
          title: Topic
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                paid:
                  summary: A paid call with signals for the topic
                  value:
                    count: 2
                    data_collected_at: '2026-10-20T18:00:04.118020+00:00'
                    generated_at: '2026-10-20T19:08:27.561515+00:00'
                    hiring_signals:
                    - category: hiring_signal
                      confidence: 0.77
                      detail: 'Backend openings up week over week | Stack: Python, FastAPI'
                      evidence:
                        company_size: 50-200
                        trend: expanding
                      source: hiring
                      timestamp: '2026-09-03T06:00:11.482913+00:00'
                      title: Series B infrastructure hiring
                    market_trends:
                    - category: trending_repo
                      confidence: 0.81
                      detail: 'Toolkit for building tool-using agents [Python] | Stars: 2,140'
                      evidence:
                        mentions: 1
                        metric: stars
                        sources:
                        - github
                        title: example-org/agent-toolkit
                      source: github
                      timestamp: '2026-10-20T19:08:27.561515+00:00'
                      title: example-org/agent-toolkit
                      url: https://github.com/example-org/agent-toolkit
                    methodology: https://gatiflow.io/methodology
                    network: eip155:8453
                    price: $0.02
                    topic: Python
              schema:
                $ref: '#/components/schemas/AgentSignals'
          description: The topic's signals. Sent with a PAYMENT-RESPONSE header (base64 JSON) carrying the settlement transaction.
        '402':
          description: 'Payment required (x402). Without a PAYMENT-SIGNATURE header, or with one the facilitator does not accept, the response carries a PAYMENT-REQUIRED header (base64 JSON) stating the price, the network, the USDC contract and the receiving address. A browser receives an HTML payment page instead. Also sent when a verified payment fails to settle: the data is withheld.'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: No signals mention the topic in the latest collection (error.details.error is no_signals), or paid calls are switched off. Not charged.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'topic is missing, shorter than 2 or longer than 60 characters, or uses characters outside letters, digits, spaces and . + # / -. error.details lists each problem. Not charged.'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'Too many requests from this address. This operation takes no credential, so the ceiling is per caller address: 30 requests a minute. Not charged.'
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'The latest collection is older than 24 hours (sent with Retry-After: 3600), or the payment facilitator cannot be reached (Retry-After: 60). Not charged.'
      security: []
      summary: Topic signals, paid per call (x402)
      tags:
      - Agent
      x-agentic-access:
        action-class: acting
        audience: https://api.gatiflow.io
        audit: none
        consequence: read
        escalation:
          human-in-the-loop: conditional
        subject: optional
      x-payment-info:
        price:
          amount: '0.02'
          currency: USD
          mode: fixed
        protocols:
        - x402: {}
components:
  schemas:
    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
    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: 'Pro and Business. The change in the signal''s stars (repositories), mentions (papers) or followers (talent) since the previous collection: previous, current, delta, delta_pct, and period_hours, the hours between the two collections.'
          title: Velocity
          type: object
      required:
      - source
      - title
      - detail
      - category
      - timestamp
      title: SignalItem
      type: object
    AgentSignals:
      description: 'One topic''s signals from the latest collection, sold per call over x402.


        Talent signals are not included, and evidence keys that name a person

        (username, author, user, owner, login, email) are dropped: the caller

        buys without an account.'
      properties:
        count:
          description: 'market_trends plus hiring_signals. Never 0: an empty result answers 404 and is not charged.'
          minimum: 1.0
          title: Count
          type: integer
        data_collected_at:
          anyOf:
          - type: string
          - type: 'null'
          description: When the collection behind the signals ran.
          format: date-time
          title: Data Collected At
        generated_at:
          format: date-time
          title: Generated At
          type: string
        hiring_signals:
          items:
            $ref: '#/components/schemas/SignalItem'
          title: Hiring Signals
          type: array
        market_trends:
          items:
            $ref: '#/components/schemas/SignalItem'
          title: Market Trends
          type: array
        methodology:
          format: uri
          title: Methodology
          type: string
        network:
          description: The CAIP-2 id of the chain the payment settled on.
          title: Network
          type: string
        price:
          description: The price this call was charged, in US dollars of USDC.
          title: Price
          type: string
        topic:
          description: The topic asked for, with runs of whitespace collapsed.
          title: Topic
          type: string
      required:
      - topic
      - data_collected_at
      - generated_at
      - market_trends
      - hiring_signals
      - count
      - price
      - network
      - methodology
      title: AgentSignals
      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
    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:
      description: When the refusal was produced, and by which API and version.
      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
  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. One published operation takes it, `GET /api/v1/public/weekly-report`. It cannot be created from an API key, and an API key sent to that operation receives 401.
      scheme: bearer
      type: http
externalDocs:
  description: API documentation
  url: https://gatiflow.io/api-docs
x-agentcash-guidance:
  llmsTxtUrl: https://gatiflow.io/llms.txt
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