Cogny Reports API
AI-powered growth report generation with streaming responses.
OpenAPI Specification
openapi: 3.1.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:
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
Error:
type: object
properties:
success:
type: boolean
enum:
- false
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
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
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
Pagination:
type: object
properties:
has_more:
type: boolean
next_cursor:
type: string
total_count:
type: integer
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: API key lacks required scope.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: Rate limit exceeded.
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