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 Usage API
  version: 2.3.0
servers:
- description: Production
  url: https://api.gatiflow.io
tags:
- name: Usage
paths:
  /api/v1/usage:
    get:
      description: 'Returns the request log for the API key used on this call: the endpoint, the HTTP status and the timestamp of each call, newest first, together with the organization name.


        The scope is the key, not the organization. An organization holding several keys sees only the activity of the key that authenticated the request, so rotating a key starts a fresh log rather than continuing the old one.


        Pass limit to change how many events come back. The default is 100 and the endpoint never returns more than 500, whatever is requested. Reading this log does not consume daily quota.'
      operationId: get_my_usage_api_v1_usage_get
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          default: 100
          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:
                no_calls:
                  summary: A key that has not been used yet
                  value:
                    org_name: Acme Capital
                    total_returned: 0
                    usage: []
                recent:
                  summary: The last few calls made with this key
                  value:
                    org_name: Acme Capital
                    total_returned: 3
                    usage:
                    - endpoint: /intelligence/report
                      status_code: 200
                      timestamp: '2026-09-03T06:00:11.482913+00:00'
                    - endpoint: /intelligence/report/export?format=csv
                      status_code: 200
                      timestamp: '2026-09-03T05:58:02.194771+00:00'
                    - endpoint: /intelligence/report
                      status_code: 429
                      timestamp: '2026-09-03T05:57:41.008320+00:00'
              schema:
                $ref: '#/components/schemas/UsageLog'
          description: Recent calls made with the API key used on this request.
        '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, or its owner's email address is still unverified after the three-day grace period.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: A parameter is missing, malformed or out of range. error.details lists each problem.
      security:
      - ApiKeyAuth: []
      summary: List recent calls made with this API key
      tags:
      - Usage
components:
  schemas:
    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
    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
    UsageLog:
      description: The request log of the API key used on the call, newest first.
      properties:
        org_name:
          title: Org Name
          type: string
        total_returned:
          title: Total Returned
          type: integer
        usage:
          items:
            $ref: '#/components/schemas/UsageEvent'
          title: Usage
          type: array
      required:
      - org_name
      - total_returned
      - usage
      title: UsageLog
      type: object
    UsageEvent:
      properties:
        endpoint:
          title: Endpoint
          type: string
        status_code:
          title: Status Code
          type: integer
        timestamp:
          anyOf:
          - type: string
          - type: 'null'
          format: date-time
          title: Timestamp
      required:
      - endpoint
      - status_code
      - timestamp
      title: UsageEvent
      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
  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