Create Report

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

Writes a report into your Confident AI project and returns its id and link. You supply the finished section content and it is stored and rendered as given.

POST/v1/reports

curl -X POST "https://api.confident-ai.com/v1/reports" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "reportTemplateId": "REPORT-TEMPLATE-ID",
  "metadata": {
    "reportTitle": "Weekly Health Check",
    "description": "Production health for the last week.",
    "dateRange": {
      "startDate": "2024-01-01T00:00:00.000Z",
      "endDate": "2024-01-08T00:00:00.000Z"
    }
  },
  "sections": [
    {
      "type": "STAT_CARDS",
      "content": {
        "cards": [
          {
            "label": "Error Rate",
            "value": "2.10%",
            "caption": "412 of 19,600 requests"
          },
          {
            "label": "Total Cost",
            "value": "$128.40"
          }
        ]
      }
    },
    {
      "type": "CONTENT",
      "heading": "Overview",
      "content": {
        "kind": "narrative",
        "narrative": "Traffic held steady while the error rate fell by a third."
      }
    },
    {
      "type": "TABLE",
      "heading": "Cost by Model",
      "content": {
        "headers": [
          "Model",
          "Total Cost"
        ],
        "rows": [
          [
            "gpt-4o",
            "$96.20"
          ],
          [
            "gpt-4o-mini",
            "$32.20"
          ]
        ]
      }
    }
  ]
}'

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 this report belongs under. Required, since reports are read under their template.
sectionslist of objectsRequired
The report's sections, in render order. At least one is required.
Show 4 propertiesHide 4 properties
- typeenumRequired
  What this section renders as. Determines the shape of content.
  Show 5 enum valuesHide 5 enum values
  - CONTENT
  - STAT_CARDS
  - TABLE
  - GRAPH
  - ADMONITION
- headingstring
  The heading rendered above the section.
- contentobject | object | object | object | objectRequired
  A section's content. Its shape is determined by the section's type — CONTENT takes narrative content, ADMONITION a callout, STAT_CARDS cards, TABLE headers and rows, and GRAPH a chart snapshot.
  Show 5 variantsHide 5 variants
  - ReportNarrativeContentobject
    The content of a CONTENT section — a block of prose.
    Show 2 propertiesHide 2 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 "- ".
  - OR
  - ReportAdmonitionContentobject
    The content of an ADMONITION section — a callout carrying a severity.
    Show 2 propertiesHide 2 properties
    severityenumRequired
    How the callout is styled.
    Show 4 enum valuesHide 4 enum values
    INFO
    SUCCESS
    WARNING
    DANGER
    textstringRequired
    One to three sentences.
  - OR
  - ReportStatCardsContentobject
    The content of a STAT_CARDS section — a row of headline numbers.
    Show 2 propertiesHide 2 properties
    cardslist of objectsRequired
    Three to five cards. 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
    One short supporting line of 10 words or fewer.
    highlightslist of objects
    At most three standout findings. Omit rather than padding.
    Show 2 propertiesHide 2 properties
    labelstringRequired
    A short Title Case phrase.
    valuestringRequired
    The highlighted value.
  - OR
  - ReportTableContentobject
    The content of a TABLE section.
    Show 2 propertiesHide 2 properties
    headerslist of stringsRequired
    The column headers. At least one is required.
    rowslist of list of stringsRequired
    The rows. Every row must contain exactly as many cells as there are headers, in the same order.
  - OR
  - ReportGraphContentobject
    The content of a GRAPH section — a chart with its data baked in. Only this snapshot form is accepted over the API, so the chart always renders exactly the numbers you supply.
    Show 6 propertiesHide 6 properties
    typeenumRequired
    Always snapshot.
    Show 1 enum valueHide 1 enum value
    snapshot
    graphTypeenumRequired
    The chart style.
    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.
    valueslist of numbersRequired
    One number per category, aligned positionally with categories.
    colorstring
    An optional colour for the series.
    xAxisLabelstring
    An optional x-axis label.
    yAxisLabelstring
    An optional y-axis label.
- startOnNewPageboolean
  Whether the section starts on a new page in the exported report.
metadataobject
The report's header information.
Show 3 propertiesHide 3 properties
- reportTitlestring
  The report's title. Defaults to the name of the report template it belongs to.
- 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 timestamp.
  - endDatestringRequired
    The end of the window, as an ISO 8601 timestamp.
statusenum
Defaults to COMPLETED, which makes the report immediately readable. Use IN_PROGRESS to add sections over several requests.
Show 3 enum valuesHide 3 enum values
- IN_PROGRESS
- COMPLETED
- ERRORED
errorstring
Why the report failed, when creating it as ERRORED.

Response

The id of the created report, and a link to read it in Confident AI.

successboolean
Indicates if the request was successful.
dataobject
The id of the affected report.
Show 1 propertyHide 1 property
- idstring
  The id of the affected report.
linkstring
Returned when creating a report — the URL where a person can read it in Confident AI. Absent on delete, and once the report's template has been deleted.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI