---
id: report-publish
title: "Publish a report"
description: "Takes a snapshot of the current draft, stores it as a new version, and marks it as the published version."
sidebar_label: "Publish a report"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "post api-method"
info_path: docs/api/reports
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Publish a report"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/report/{id}/publish"}
  context={"endpoint"}
>
  
</MethodEndpoint>



Takes a snapshot of the current draft, stores it as a new version, and marks it as the published version.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier of the report.","example":"ff5970bf-592d-4a8d-b858-3175ec444562"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The newly published version.","content":{"application/json":{"schema":{"title":"ReportVersion","type":"object","description":"An immutable snapshot of a report's draft, taken when the report was published.","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of this version.","example":"183ab994-792a-412a-91fa-60552ff1aa7f"},"report_id":{"type":"string","format":"uuid","description":"The ID of the report this version belongs to.","example":"ff5970bf-592d-4a8d-b858-3175ec444562"},"version_number":{"type":"integer","description":"The sequential version number, starting at 1.","example":1},"name":{"type":"string","description":"The report's display name at the time this version was published.","example":"Deployment frequency"},"slug":{"type":"string","description":"The report's slug at the time this version was published.","example":"deployment-frequency"},"description":{"type":"string","description":"The report's description at the time this version was published.","example":"How often each application deploys"},"schema":{"type":"object","additionalProperties":true,"description":"The JSON Schema snapshot included in this version."},"ui_schema":{"type":"object","additionalProperties":true,"description":"The UI Schema snapshot included in this version."},"queries":{"title":"Queries","type":"object","description":"A map of query IDs to query definitions. Each ID is a name you choose to identify the query within the report.","additionalProperties":{"title":"QueryDefinition","type":"object","required":["source"],"additionalProperties":false,"properties":{"source":{"type":"string","description":"The SQL `SELECT` statement the query runs. It can include `{name:Type}` placeholders that take their values from form fields, as declared in `params`.","example":"SELECT name FROM environments WHERE account = {account:String}"},"params":{"type":"object","description":"Binds the placeholders in `source` to form fields. Each key matches a placeholder name in the query.","additionalProperties":{"type":"object","required":["scope"],"additionalProperties":false,"properties":{"scope":{"type":"string","description":"A JSON Pointer to the form field that supplies the placeholder's value.","example":"#/properties/account"}}}},"target":{"type":"string","description":"A JSON Pointer to the schema property this query populates with its results.","example":"#/properties/environment"},"mapping":{"type":"string","enum":["enum"],"description":"How query results map onto the `target` field. Use `enum` to turn the results into the field's selectable options.","example":"enum"}}}},"visibility":{"title":"Visibility","type":"string","enum":["user","organization"],"description":"Who can see the report. `user` keeps it private to its owner; `organization` shares it with the whole organization.","example":"user"},"published_by":{"type":"string","description":"The ID of the user who published this version.","example":"1234"},"created_at":{"type":"string","format":"date-time","description":"The ISO 8601 timestamp of when this version was published.","example":"2026-07-20T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"The ISO 8601 timestamp of this version's last update.","example":"2026-07-20T12:00:00Z"}}}}}},"4XX":{"description":"Client error responses due to invalid input or missing parameters.","content":{"application/json":{"schema":{"title":"Error","type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code indicating the error.","example":400},"code":{"type":"string","description":"A machine-readable error code that categorizes the failure.","example":"bad_request"},"error":{"type":"string","description":"A short, human-readable error type.","example":"Bad Request"},"message":{"type":"string","description":"Additional details about the error.","example":"The request was malformed or contained invalid parameters."}}}}}},"5XX":{"description":"Internal server error due to an unexpected issue.","content":{"application/json":{"schema":{"title":"Error","type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code indicating the error.","example":400},"code":{"type":"string","description":"A machine-readable error code that categorizes the failure.","example":"bad_request"},"error":{"type":"string","description":"A short, human-readable error type.","example":"Bad Request"},"message":{"type":"string","description":"Additional details about the error.","example":"The request was malformed or contained invalid parameters."}}}}}}}}
>
  
</StatusCodes>