Create a Custom Chart With the API

POST /dashboards/{dashboardId}/gadgets

Query parameters

Name	Type	Default	Description
`validateUniqueSource`	boolean	`false`	When `true` and source fields are provided, the API rejects the create with `409` if any existing gadget on the dashboard already carries the same `sourceGadgetId`. Costs N property fetches.

Request body

{
  "gadgetType": "custom-chart-dashboard-item",
  "position": { "column": 0, "row": 0 },
  "color": "green",
  "title": "Issues by status",
  "sourceGadgetId": 1234,
  "sourceDashboardId": 5678,
  "sourceSiteUrl": "https://other-site.atlassian.net",
  "configuration": { /* gadget-type-specific JSON */ },
  "fieldMapping": null
}

Field	Type	Required	Notes
`gadgetType`	`string`	yes	Must be one of the supported types.
`position`	object	yes	Both `column` and `row` are required.
`position.column`	`int`	yes	Zero-based column index.
`position.row`	`int`	yes	Zero-based row index.
`color`	`string`	no	Jira-defined color name.
`title`	`string`	no	Gadget title.
`sourceGadgetId`	`long`	no	All-or-none with the other two source fields.
`sourceDashboardId`	`long`	no	All-or-none with the other two source fields.
`sourceSiteUrl`	`string`	no	All-or-none; must be non-blank when set.
`configuration`	object	yes	Gadget-type-specific configuration JSON.
`fieldMapping`	object	no	Currently accepted but not persisted. Reserved for a future iteration.

Response — `200 OK`

A Gadget object reflecting the newly created gadget. Source fields and configuration are echoed from the request.

Errors

Status	When
`400`	`gadgetType` invalid, `configuration` missing, `position`/`column`/`row` missing, partial source fields.
`409`	`validateUniqueSource=true` and a gadget with the same `sourceGadgetId` already exists.

Query parameters

Request body

Response — 200 OK

Errors

Response — `200 OK`