Cogny

Cogny Reports API

AI-powered growth report generation with streaming responses.

GitHub OpenAPI

Operations 6

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /reports List growth reports · List reports #
Ask an LLM
“Which growth reports have I generated so far in Cogny?”
“Can I see only the reports that ran against one particular warehouse?”
Tell an agent
List all my growth reports.
List reports for warehouse {warehouse_id} with status {status}.
POST /reports Start an AI-generated growth report · Create a report #
Ask an LLM
“How do I ask a plain-English question and get an AI growth report from my warehouse data?”
“Can I give extra context along with my prompt when generating a new report?”
Tell an agent
Generate a new report on warehouse {warehouse_id} answering: {prompt}
Kick off a growth report over {warehouse_id} for "{prompt}" using this background: {context}.
GET /reports/{report_id} Check a report's status · Get report status #
Ask an LLM
“Is my growth report finished yet or still generating?”
“What's the current state of a report I started earlier?”
Tell an agent
Check the status of report {report_id}.
Tell me whether report {report_id} has completed or failed.
DELETE /reports/{report_id} Cancel a report in progress · Cancel a report #
Ask an LLM
“Can I stop a growth report that's taking too long to generate?”
“How do I cancel a report I kicked off by mistake?”
Tell an agent destructive · confirm first
Cancel report {report_id}.
Abort the generation of report {report_id} now.
GET /reports/{report_id}/stream Stream live progress of a report · Stream report generation (SSE) #
Ask an LLM
“Can I watch a report's queries, insights and charts appear live as it's being generated?”
“What events does the server-sent events feed emit while a report is building?”
Tell an agent
Stream the live generation events for report {report_id}.
Follow report {report_id} over SSE until it completes or errors.
GET /reports/{report_id}/content Get a finished report's content · Get report content #
Ask an LLM
“Where do I fetch the full findings of a completed growth report?”
“Can I pull the final written content of a report once it's done?”
Tell an agent
Fetch the content of report {report_id}.
Give me the full findings from finished report {report_id}.

Documentation

📖
APIReference
https://cogny.com/docs/api-overview-authentication

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/cogny/refs/heads/main/openapi/cogny-reports-api-openapi.yml

Other Resources

🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/cogny/refs/heads/main/apis.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/cogny:cogny-reports-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

cogny-reports-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Cogny Reports API
  version: '1'
  description: Cogny is an AI marketing platform. The REST API exposes the Report Builder (AI-generated growth reports with SSE streaming), Growth Tickets, and warehouse resources. Authentication is a Bearer API key (sk_live_* / sk_test_*).
  contact:
    name: Cogny
    url: https://cogny.com
  termsOfService: https://cogny.com/terms
servers:
- url: https://api.cogny.com/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Reports
  description: AI-powered growth report generation with streaming responses.
paths:
  /reports:
    get:
      operationId: listReports
      summary: List reports
      tags:
      - Reports
      security:
      - bearerAuth:
        - reports:read
      parameters:
      - name: warehouse_id
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          - cancelled
      - name: created_after
        in: query
        schema:
          type: string
          format: date-time
      - name: created_before
        in: query
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 100
      - name: cursor
        in: query
        schema:
          type: string
      responses:
        '200':
          description: A page of reports.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Report'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createReport
      summary: Create a report
      description: Start an AI-generated growth report from a natural-language prompt over a connected warehouse.
      tags:
      - Reports
      security:
      - bearerAuth:
        - reports:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReportRequest'
      responses:
        '201':
          description: Report accepted for processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Report'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /reports/{report_id}:
    parameters:
    - name: report_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getReport
      summary: Get report status
      tags:
      - Reports
      security:
      - bearerAuth:
        - reports:read
      responses:
        '200':
          description: Report status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Report'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: cancelReport
      summary: Cancel a report
      tags:
      - Reports
      security:
      - bearerAuth:
        - reports:write
      responses:
        '200':
          description: Report cancelled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      status:
                        type: string
                        enum:
                        - cancelled
                      cancelled_at:
                        type: string
                        format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /reports/{report_id}/stream:
    parameters:
    - name: report_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: streamReport
      summary: Stream report generation (SSE)
      description: 'Server-Sent Events stream of report generation. Event types: status, query, result, insight, visualization, completed, error.'
      tags:
      - Reports
      security:
      - bearerAuth:
        - reports:read
      responses:
        '200':
          description: An SSE stream.
          content:
            text/event-stream:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /reports/{report_id}/content:
    parameters:
    - name: report_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getReportContent
      summary: Get report content
      tags:
      - Reports
      security:
      - bearerAuth:
        - reports:read
      responses:
        '200':
          description: Full report content with sections, insights, visualizations, recommendations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/ReportContent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
    Insight:
      type: object
      properties:
        type:
          type: string
        content:
          type: string
        confidence:
          type: number
        data:
          type: object
    CreateReportRequest:
      type: object
      required:
      - warehouse_id
      - prompt
      properties:
        warehouse_id:
          type: string
        prompt:
          type: string
          maxLength: 2000
        context:
          type: object
          properties:
            date_range:
              type: object
              properties:
                start:
                  type: string
                  format: date
                end:
                  type: string
                  format: date
            dimensions:
              type: array
              items:
                type: string
            focus_areas:
              type: array
              items:
                type: string
        options:
          type: object
          properties:
            include_visualizations:
              type: boolean
              default: true
            include_sql_queries:
              type: boolean
              default: false
            include_recommendations:
              type: boolean
              default: true
            max_iterations:
              type: integer
              default: 50
              maximum: 100
            language:
              type: string
              default: en
        metadata:
          type: object
    Pagination:
      type: object
      properties:
        has_more:
          type: boolean
        next_cursor:
          type: string
        total_count:
          type: integer
    ReportContent:
      type: object
      properties:
        report_id:
          type: string
        sections:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              content:
                type: string
              insights:
                type: array
                items:
                  $ref: '#/components/schemas/Insight'
              visualizations:
                type: array
                items:
                  type: object
              queries:
                type: array
                items:
                  type: object
        recommendations:
          type: array
          items:
            type: object
            properties:
              priority:
                type: string
                enum:
                - high
                - medium
                - low
              title:
                type: string
              description:
                type: string
              estimated_impact:
                type: string
              effort:
                type: string
              action_items:
                type: array
                items:
                  type: string
        metadata:
          type: object
          properties:
            total_queries:
              type: integer
            total_insights:
              type: integer
            generation_time_seconds:
              type: number
    Report:
      type: object
      properties:
        id:
          type: string
        warehouse_id:
          type: string
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          - cancelled
        prompt:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        estimated_completion:
          type: string
          format: date-time
        url:
          type: string
        stream_url:
          type: string
        summary:
          type: object
          properties:
            total_queries:
              type: integer
            total_insights:
              type: integer
            key_findings:
              type: array
              items:
                type: string
        metadata:
          type: object
  responses:
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: API key lacks required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer API key. Production keys are prefixed sk_live_, test keys sk_test_. MCP-issued anonymous keys are prefixed cogny_lite_.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Legacy API-key header (equivalent to Bearer).
    oauth2:
      type: oauth2
      description: OAuth 2.1 (DCR + PKCE) for MCP clients.
      flows:
        authorizationCode:
          authorizationUrl: https://cogny.com/api/mcp/oauth/authorize
          tokenUrl: https://cogny.com/api/mcp/oauth/token
          scopes:
            read: Read access
            write: Write access
            tickets:read: Read tickets
            tickets:write: Write tickets