Create Report

POSThttps://api.confident-ai.com/v2/reports

Writes a report into your Confident AI project and returns its id. You supply the finished section content and it is stored and rendered exactly as given, under the report template you name.

POST/v2/reports

curl -X POST "https://api.confident-ai.com/v2/reports" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "reportTemplateId": "<REPORT-TEMPLATE-ID>",
  "status": "IN_PROGRESS",
  "error": null,
  "metadata": {
    "reportTitle": "Weekly Health Check",
    "description": "Production health for the last week.",
    "dateRange": {
      "startDate": "2025-01-01T00:00:00.000Z",
      "endDate": "2025-01-08T00:00:00.000Z"
    }
  },
  "sections": [
    {
      "type": "CONTENT",
      "heading": "Overview",
      "startOnNewPage": false,
      "content": {
        "kind": "narrative",
        "narrative": "Traffic held steady while the error rate fell by a third, and spend stayed inside budget.",
        "sources": [
          "Traces, 1-8 Jan 2025"
        ]
      }
    }
  ]
}'

200

{
  "success": true,
  "data": {
    "id": "<REPORT-ID>"
  },
  "link": "https://app.confident-ai.com/project/<PROJECT-ID>/reports/<REPORT-TEMPLATE-ID>?reportId=<REPORT-ID>",
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Request body

reportTemplateIdstringRequired
The report template to write this report under. Required, since a report is read under its template.
statusenum
Where a report is in its life: IN_PROGRESS while its sections are still being written, COMPLETED once it is readable, ERRORED when writing it failed.
Show 3 enum valuesHide 3 enum values
- IN_PROGRESS
- COMPLETED
- ERRORED
errorstring | null
Why the report failed, when creating it as ERRORED.
metadataobject
The report's header information. Confident AI stamps generatedAt itself.
Show 3 propertiesHide 3 properties
- reportTitlestring
  The report's title. Defaults to the name of the report template it is written under.
- descriptionstring
  One line on what the report covers.
- dateRangeobject
  The window a report describes, shown in its header.
  Show 2 propertiesHide 2 properties
  - startDatestringRequired
    The start of the window, as an ISO 8601 datetime.
  - endDatestringRequired
    The end of the window, as an ISO 8601 datetime.
sectionslist of object | object | object | object | objectRequired
The report's sections, in render order. At least one is required.
Show 5 variantsHide 5 variants
- Content Sectionobject
  A section of prose.
  Show 4 propertiesHide 4 properties
  - typeenumRequired
    Always CONTENT.
    Show 1 enum valueHide 1 enum value
    CONTENT
  - headingstring | null
    The heading rendered above the section. Omit it for an unheaded section.
  - startOnNewPageboolean
    Whether the section starts on a new page in the exported report. Defaults to false.
  - contentobjectRequired
    The content of a CONTENT section — a block of prose.
    Show 3 propertiesHide 3 properties
    kindenumRequired
    Always narrative.
    Show 1 enum valueHide 1 enum value
    narrative
    narrativestringRequired
    Plain text only — no markdown headings, bold, or code fences. Do not repeat the section's heading, which renders above this text. Express a list as one item per line, each starting with "- ".
    sourcesarray | null
    Reader-facing labels for the data this section draws on, rendered beneath it. Omit them unless you want the section to cite where its numbers came from.
- OR
- Admonition Sectionobject
  A callout box carrying a severity.
  Show 4 propertiesHide 4 properties
  - typeenumRequired
    Always ADMONITION.
    Show 1 enum valueHide 1 enum value
    ADMONITION
  - headingstring | null
    The heading rendered above the section. Omit it for an unheaded section.
  - startOnNewPageboolean
    Whether the section starts on a new page in the exported report. Defaults to false.
  - contentobjectRequired
    The content of an ADMONITION section — a callout carrying a severity.
    Show 3 propertiesHide 3 properties
    severityenumRequired
    How an ADMONITION section's callout is styled.
    Show 4 enum valuesHide 4 enum values
    INFO
    SUCCESS
    WARNING
    DANGER
    textstringRequired
    One to three sentences.
    sourcesarray | null
    Reader-facing labels for the data this section draws on, rendered beneath it. Omit them unless you want the section to cite where its numbers came from.
- OR
- Stat Cards Sectionobject
  A row of headline numbers.
  Show 4 propertiesHide 4 properties
  - typeenumRequired
    Always STAT_CARDS.
    Show 1 enum valueHide 1 enum value
    STAT_CARDS
  - headingstring | null
    The heading rendered above the section. Omit it for an unheaded section.
  - startOnNewPageboolean
    Whether the section starts on a new page in the exported report. Defaults to false.
  - contentobjectRequired
    The content of a STAT_CARDS section — a row of headline numbers.
    Show 3 propertiesHide 3 properties
    cardslist of objectsRequired
    Three to five cards read best. At least one is required.
    Show 3 propertiesHide 3 properties
    labelstringRequired
    A short Title Case phrase of 2-4 words — never a sentence or a raw column name.
    valuestringRequired
    A number, percentage, or short phrase, with numbers rounded to 2 decimal places.
    captionstring | null
    One short supporting line of 10 words or fewer.
    highlightsarray | null
    At most three standout findings. Omit rather than padding.
    Show 2 propertiesHide 2 properties
    labelstringRequired
    A short Title Case phrase.
    valuestringRequired
    The highlighted value.
    sourcesarray | null
    Reader-facing labels for the data this section draws on, rendered beneath it. Omit them unless you want the section to cite where its numbers came from.
- OR
- Table Sectionobject
  A grid of headers and rows.
  Show 4 propertiesHide 4 properties
  - typeenumRequired
    Always TABLE.
    Show 1 enum valueHide 1 enum value
    TABLE
  - headingstring | null
    The heading rendered above the section. Omit it for an unheaded section.
  - startOnNewPageboolean
    Whether the section starts on a new page in the exported report. Defaults to false.
  - contentobjectRequired
    The content of a TABLE section — headers and the rows beneath them.
    Show 3 propertiesHide 3 properties
    headerslist of stringsRequired
    The column headers. At least one is required.
    rowslist of list of stringsRequired
    The rows. Every row must hold exactly as many cells as there are headers, in the same order.
    sourcesarray | null
    Reader-facing labels for the data this section draws on, rendered beneath it. Omit them unless you want the section to cite where its numbers came from.
- OR
- Graph Sectionobject
  A chart plotting the numbers you supply.
  Show 4 propertiesHide 4 properties
  - typeenumRequired
    Always GRAPH.
    Show 1 enum valueHide 1 enum value
    GRAPH
  - headingstring | null
    The heading rendered above the section. Omit it for an unheaded section.
  - startOnNewPageboolean
    Whether the section starts on a new page in the exported report. Defaults to false.
  - contentobjectRequired
    The content of a GRAPH section — a chart with its data baked in. This is the only chart form you can write over the API, so the chart always renders exactly the numbers you supply.
    Show 7 propertiesHide 7 properties
    typeenumRequired
    Always snapshot.
    Show 1 enum valueHide 1 enum value
    snapshot
    graphTypeenumRequired
    The chart style a GRAPH section renders as.
    Show 4 enum valuesHide 4 enum values
    LINE
    AREA
    BAR
    STACKED_BAR
    categorieslist of stringsRequired
    The x-axis labels. At least one is required.
    serieslist of objectsRequired
    One entry per plotted line. Every series' values must be the same length as categories.
    Show 3 propertiesHide 3 properties
    namestringRequired
    The series label, which doubles as its legend entry.
    valueslist of numbersRequired
    One number per category, aligned positionally with them.
    colorstring | null
    A colour for the series. Confident AI picks one when omitted.
    xAxisLabelstring | null
    A label for the x-axis.
    yAxisLabelstring | null
    A label for the y-axis.
    sourcesarray | null
    Reader-facing labels for the data this section draws on, rendered beneath it. Omit them unless you want the section to cite where its numbers came from.

Response

Create Report succeeded.

successboolean
Indicates if the request was successful.
dataobject
A reference to a report by its id.
Show 1 propertyHide 1 property
- idstring
  The id of the report, generated by Confident AI.
linkstring
This is the URL of the resource on the Confident AI platform.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI