---
id: report-create
title: "Create a report"
description: "Creates a new dynamic report. Only `name` is required. If `visibility` is omitted, the report is created as `user`."
sidebar_label: "Create 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={"Create a report"}
>
</Heading>

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



Creates a new dynamic report. Only `name` is required. If `visibility` is omitted, the report is created as `user`.

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

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"title":"ReportCreate","type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The report's display name. This is the only required field.","example":"Deployment frequency"},"slug":{"type":"string","description":"A URL-friendly identifier for the report.","example":"deployment-frequency"},"description":{"type":"string","description":"A human-readable description of what the report shows.","example":"How often each application deploys"},"schema":{"type":"object","additionalProperties":true,"description":"A JSON Schema defining the report's input fields."},"ui_schema":{"type":"object","additionalProperties":true,"description":"A UI Schema controlling how the form renders."},"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"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"The report was created.","content":{"application/json":{"schema":{"title":"Report","type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The unique report identifier.","example":"ff5970bf-592d-4a8d-b858-3175ec444562"},"name":{"type":"string","description":"The report's display name.","example":"Deployment frequency"},"slug":{"type":"string","description":"A URL-friendly identifier for the report.","example":"deployment-frequency"},"description":{"type":"string","description":"A human-readable description of what the report shows.","example":"How often each application deploys"},"schema":{"type":"object","additionalProperties":true,"description":"A JSON Schema defining the report's input fields."},"ui_schema":{"type":"object","additionalProperties":true,"description":"A UI Schema controlling how the form renders."},"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"},"created_at":{"type":"string","format":"date-time","description":"The ISO 8601 timestamp of when the report was created.","example":"2026-07-20T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"The ISO 8601 timestamp of the report'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>