API Documentation
GatiFlow provides a RESTful JSON API for programmatic access to intelligence reports, signal data, and organization management.
Use Cases
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 shows every call a scheduled job made without a second log.
Quick Start
1. Register at /register
2. Create an API key on the API Keys page
3. Make your first request:
curl -H "X-API-Key: gf_your_key_here" \ https://api.gatiflow.io/api/v1/intelligence/report
Interactive Docs
Full OpenAPI documentation with try-it-out functionality:
Machine-readable
The contract, for a client generator, a catalog or an agent — not a page about the API, the API:
/openapi.json — OpenAPI 3.1. Every published operation with its parameters, response shapes and a worked example, including the empty states. Generated from the running routes and compared against them by the test suite, so it cannot drift from the API it describes.
/apis.json — APIs.json index: the API, its base URL and every document that describes it.
/llms.txt — the same surface in plain language, for a reader with no one watching.
/asyncapi.json — AsyncAPI 3.0: the webhook GatiFlow sends, generated from the webhooks section of the contract above.
/postman_collection.json — a Postman collection with one request per operation. Set apiKey and send.
/schemas/<Name>.json — one JSON Schema per response a caller receives, for example IntelligenceReport, generated from the contract's component schemas.
/.well-known/api-catalog — the RFC 9727 catalog an agent tries first, and /.well-known/security.txt for reporting a vulnerability.
api.gatiflow.io/sbom.cdx.json — the software bill of materials of the running API, in CycloneDX, read from the packages the service has installed.
Webhooks
On Pro and Business, alerts that match your watchlist are pushed to the HTTPS endpoints you register in Settings, signed with HMAC-SHA256. Webhooks describes the payload, the signature, delivery timing and retries.
Examples
Code examples in curl, Python and JavaScript for every operation below that an API key, or no credential, can call.
Authentication
Every operation below takes an API key (prefix gf_) in the X-API-Key header, with two exceptions: GET /api/v1/public/deep-dive takes no credential, and GET /api/v1/public/weekly-report takes the web-app session bearer instead, so an API key receives 401 there. Keys grant read access to intelligence data and support optional expiration dates.
Rate Limits
Rate Limits (requests per minute): Free 5 · Starter 60 · Pro 120 · Business 300.
Daily Quota: Free 10/day · Starter 2,000/day · Pro 10,000/day · Business 50,000/day.
Both apply per organization: every API key an organization holds draws on the same per-minute limit and the same daily quota. The per-minute limit comes back in X-RateLimit-* headers and the daily quota in X-DailyQuota-*, on the operations that meter them; the contract states which, per response. See /billing for full plan comparison.
Errors
Every error has the same shape: status is error, error.message says why, error.code is NOT_FOUND for a 404, VALIDATION_ERROR for a 422 (with each problem listed in error.details) and HTTP_ERROR otherwise, and error.request_id, also sent as the X-Request-ID header, is the id to quote when you write to support. The 503 on the report and the export carries a structured error.message and a Retry-After header. The contract types every error response.
Versioning and deprecation
The version is in the path: every published operation lives under /api/v1. Additive changes ship without notice: a new operation, a new optional parameter, a new field in a response. Clients should ignore fields they do not know. A breaking change (removing or renaming an operation, a parameter or a field, or changing its type or meaning) ships only under a new version path, next to the current one.
Deprecation. An operation or a version is removed no sooner than 90 days after its deprecation is announced. The notice goes by email to the owner of every organization holding an active API key and into the changelog; the operation is marked deprecated in the contract; and from the day of the notice its responses carry a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) with the removal date.
Support lifetime. A version receives fixes, security fixes included, until its Sunset date, and it is never sunset less than 90 days after its successor is published. No operation is deprecated today.
What is planned next is on the roadmap.
Endpoints
GET /api/v1/intelligence/report — Full intelligence report (content scales with plan)
GET /api/v1/intelligence/report/export?format=csv — Export signals as CSV (Pro/Business only)
GET /api/v1/intelligence/report/export?format=pdf — Export signals as PDF (Business only)
GET /api/v1/intelligence/report-history — Report snapshot history (?limit=N, 1–50; retention varies by plan, Free excluded)
GET /api/v1/intelligence/report/at/{snapshot_id} — One archived report by id (ids come from report-history, format YYYYMMDDTHHmm)
GET /api/v1/usage — Recent calls made with this API key (?limit=N, default 100, max 500)
GET /api/v1/public/weekly-report — Daily Insights (web-app session; an API key receives 401)
GET /api/v1/public/deep-dive — Latest deep dive preview: title, excerpt and word count (no auth), and the address where the full article is free to read