Update Report

PUThttps://api.confident-ai.com/v2/reports/{reportId}

Updates a report and returns it. Only the fields you send are changed: metadata is merged onto the report's stored header, while sections replaces its section list wholesale.

PUT/v2/reports/{reportId}

curl -X PUT "https://api.confident-ai.com/v2/reports/{reportId}" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "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>",
    "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"
      },
      "generatedAt": "2025-01-08T00:00:00.000Z"
    },
    "createdAt": "2025-01-08T00:00:00.000Z",
    "updatedAt": "2025-01-08T00:00:00.000Z",
    "sections": [
      {
        "id": "<REPORT-SECTION-ID>",
        "type": "CONTENT",
        "heading": "Overview",
        "order": 0,
        "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"
          ]
        },
        "error": null,
        "startOnNewPage": false
      }
    ]
  },
  "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.

Path parameters

reportIdstringRequired
The id of the report.

Request body

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. Pair it with a status of ERRORED, or send null to clear it.
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 | object
The report's sections, in render order. The list replaces the report's current sections rather than adding to them.
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

Update Report succeeded.

successboolean
Indicates if the request was successful.
dataobject
A report written under a report template, with every section it renders.
Show 8 propertiesHide 8 properties
- idstring
  The id of the report, generated by Confident AI.
- reportTemplateIdstring | null
  The id of the report template this report is written under, or null once that template has been deleted, which leaves the report unreachable on the platform.
- 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 it did.
- metadataobject | null
  The report's stored header information. A field the report was written without comes back as null.
  Show 4 propertiesHide 4 properties
  - reportTitlestring | null
    The report's title, as rendered in its header.
  - descriptionstring | null
    One line on what the report covers.
  - dateRangeobject | null
    The window a report describes, shown in its header.
    Show 2 propertiesHide 2 properties
    startDatestring
    The start of the window, as an ISO 8601 datetime.
    endDatestring
    The end of the window, as an ISO 8601 datetime.
  - generatedAtstring | null
    When the report was written. Always stamped by Confident AI.
- createdAtstring
  When the report was created.
- updatedAtstring
  When the report was last updated.
- sectionslist of objects
  The report's sections, ordered as they render.
  Show 7 propertiesHide 7 properties
  - idstring
    The id of the section, generated by Confident AI.
  - typeenum
    What a section renders as, which decides the shape of its content: CONTENT is prose, ADMONITION a callout, STAT_CARDS a row of headline numbers, TABLE a grid, and GRAPH a chart.
    Show 5 enum valuesHide 5 enum values
    CONTENT
    STAT_CARDS
    TABLE
    GRAPH
    ADMONITION
  - headingstring | null
    The heading rendered above the section, or null when it has none.
  - orderinteger
    The section's position in the report, starting at 0.
  - contentobject | object | object | object | object | object | null
    Show 7 variantsHide 7 variants
    Narrative Contentobject
    The content of a CONTENT section — a block of prose.
    Show 3 propertiesHide 3 properties
    kindenum
    Always narrative.
    Show 1 enum valueHide 1 enum value
    narrative
    narrativestring
    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 Contentobject
    The content of an ADMONITION section — a callout carrying a severity.
    Show 3 propertiesHide 3 properties
    severityenum
    How an ADMONITION section's callout is styled.
    Show 4 enum valuesHide 4 enum values
    INFO
    SUCCESS
    WARNING
    DANGER
    textstring
    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 Contentobject
    The content of a STAT_CARDS section — a row of headline numbers.
    Show 3 propertiesHide 3 properties
    cardslist of objects
    Three to five cards read best. At least one is required.
    Show 3 propertiesHide 3 properties
    labelstring
    A short Title Case phrase of 2-4 words — never a sentence or a raw column name.
    valuestring
    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
    labelstring
    A short Title Case phrase.
    valuestring
    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 Contentobject
    The content of a TABLE section — headers and the rows beneath them.
    Show 3 propertiesHide 3 properties
    headerslist of strings
    The column headers. At least one is required.
    rowslist of list of strings
    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 Contentobject
    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
    typeenum
    Always snapshot.
    Show 1 enum valueHide 1 enum value
    snapshot
    graphTypeenum
    The chart style a GRAPH section renders as.
    Show 4 enum valuesHide 4 enum values
    LINE
    AREA
    BAR
    STACKED_BAR
    categorieslist of strings
    The x-axis labels. At least one is required.
    serieslist of objects
    One entry per plotted line. Every series' values must be the same length as categories.
    Show 3 propertiesHide 3 properties
    namestring
    The series label, which doubles as its legend entry.
    valueslist of numbers
    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.
    OR
    Graph Config Contentobject
    The content of a GRAPH section that Confident AI generated as a live query rather than a snapshot. It carries no data of its own: the query is run against your project when the report is rendered. Read-only — a chart you write yourself is always a snapshot.
    Show 11 propertiesHide 11 properties
    typeenum
    Always config.
    Show 1 enum valueHide 1 enum value
    config
    sourcestring | null
    Which data source resolves the query.
    titlestring
    The chart title.
    dataModelstring
    The data model queried, such as TRACE, SPAN or METRIC_DATA.
    metricstring
    The aggregate plotted, such as error_rate or total_cost.
    dimensionstring | null
    The property the metric is split by, giving one line per value. Null for a plain trend over time.
    granularitystring | null
    The time bucket, such as hour, day, week or month.
    spanTypestring | null
    The span type queried, for SPAN charts only.
    startDatestring | null
    The start of the queried window as an ISO 8601 datetime, pinning the chart to a point in time.
    endDatestring | null
    The end of the queried window as an ISO 8601 datetime.
    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
    null
  - errorstring | null
    Why this section failed to generate, when it did.
  - startOnNewPageboolean | null
    Whether the section starts on a new page in the exported report.
linkstring
This is the URL of the resource on the Confident AI platform.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI