---
title: "Chord Diagram API — Custom-colored relationship charts | Imejis"
description: "Generate chord diagrams in your brand palette — arcs and ribbons colored to match — with relationships set per API call. Try Imejis free."
url: "https://www.imejis.io/components/chord/palette"
---

# Chord Diagram API — Custom-colored relationship charts | Imejis

Brand the arcs with your own colors.

## Use cases

- Brand-colored relationship graphics
- Category-coded connection maps
- Report-ready chord charts

## Properties

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `links` | `object[]` | `[]` | Relationships: array of { source, target, value } — names reference groups. |
| `groups` | `object[]` | `[]` | Optional group colors/order: [{ name, color }]; derived from links otherwise. |
| `colors` | `color[]` | `[]` | Group palette (cycled) when a group has no explicit color. |
| `padAngle` | `number` (min 0) | `2` | Gap between group arcs (degrees). |
| `arcThickness` | `number` (min 1) | `14` | Thickness of the group ring band (px). |
| `ribbonOpacity` | `number` (min 0, max 1) | `0.6` | Opacity of the relationship ribbons. |
| `labelColor` | `color` | `"#334155"` | Group label text color. |
| `showValues` | `boolean` | `false` | Append each group's total to its label. |
| `valueFormat` | `'number' \| 'compact' \| 'percent' \| 'currency'` | `"compact"` | How printed values are formatted (1,200 / 1.2K / $1,200). |
| `currencySymbol` | `string` | `"$"` | Symbol used with the 'currency' format. |
| `opacity` | `number` | `1` | Overall component opacity from 0 (transparent) to 1 (opaque). |
| `borderWidth` | `number` | `0` | Border thickness in pixels around the component. |
| `borderColor` | `color` | `"transparent"` | Border color (any CSS color). |
| `borderStyle` | `'solid' \| 'dashed' \| 'dotted' \| 'double' \| 'none'` | `"solid"` | Border line style. |
| `borderRadius` | `number` | `0` | Corner radius in pixels. |
| `boxShadow` | `string` | — | CSS box-shadow applied to the component, e.g. "0 4px 6px rgba(0,0,0,0.1)". |

## Design JSON (this variant)

```json
{
  "title": "Chord sample",
  "description": "Migration flows between regions",
  "dimensions": {
    "width": 620,
    "height": 480
  },
  "background": {
    "color": "#ffffff"
  },
  "components": [
    {
      "id": "sample-chord",
      "key": "chord",
      "type": "chord",
      "position": {
        "x": 150,
        "y": 40
      },
      "rotation": 0,
      "size": {
        "width": 400,
        "height": 400
      },
      "dynamic": true,
      "properties": {
        "links": [
          {
            "source": "North",
            "target": "South",
            "value": 40
          },
          {
            "source": "North",
            "target": "East",
            "value": 25
          },
          {
            "source": "North",
            "target": "West",
            "value": 15
          },
          {
            "source": "South",
            "target": "East",
            "value": 30
          },
          {
            "source": "South",
            "target": "West",
            "value": 20
          },
          {
            "source": "East",
            "target": "West",
            "value": 22
          }
        ],
        "padAngle": 2,
        "ribbonOpacity": 0.6,
        "showValues": true,
        "opacity": 1,
        "colors": [
          "#2563eb",
          "#7c3aed",
          "#c026d3",
          "#db2777",
          "#ea580c",
          "#0891b2"
        ]
      }
    }
  ]
}
```

## Examples

### Channel referrals

Which channels refer to which, in a brand palette.

API overrides that reproduce this example:

```json
{
  "chord.colors": [
    "#2563eb",
    "#7c3aed",
    "#c026d3",
    "#db2777",
    "#ea580c"
  ],
  "chord.links": [
    {
      "source": "Blog",
      "target": "Docs",
      "value": 36
    },
    {
      "source": "Blog",
      "target": "Pricing",
      "value": 28
    },
    {
      "source": "Docs",
      "target": "Signup",
      "value": 40
    },
    {
      "source": "Pricing",
      "target": "Signup",
      "value": 32
    },
    {
      "source": "Signup",
      "target": "Blog",
      "value": 12
    }
  ]
}
```

### Genre crossovers

Shared listeners between music genres.

API overrides that reproduce this example:

```json
{
  "chord.colors": [
    "#f43f5e",
    "#8b5cf6",
    "#0ea5e9",
    "#22c55e",
    "#f59e0b"
  ],
  "chord.links": [
    {
      "source": "Pop",
      "target": "Rock",
      "value": 50
    },
    {
      "source": "Pop",
      "target": "Hip-hop",
      "value": 44
    },
    {
      "source": "Rock",
      "target": "Metal",
      "value": 30
    },
    {
      "source": "Hip-hop",
      "target": "R&B",
      "value": 38
    },
    {
      "source": "R&B",
      "target": "Pop",
      "value": 26
    }
  ]
}
```

## API overrides

Push fresh relationships per render with '<key>.links' (or just '<key>') as [{ source, target, value }]; group colors via '<key>.groups'.

Flat override payload (`key.property` addressing) with the sample design's current values — send only the keys you want to change:

```json
{
  "chord.links": [
    {
      "source": "North",
      "target": "South",
      "value": 40
    },
    {
      "source": "North",
      "target": "East",
      "value": 25
    },
    {
      "source": "North",
      "target": "West",
      "value": 15
    },
    {
      "source": "South",
      "target": "East",
      "value": 30
    },
    {
      "source": "South",
      "target": "West",
      "value": 20
    },
    {
      "source": "East",
      "target": "West",
      "value": 22
    }
  ],
  "chord.padAngle": 2,
  "chord.ribbonOpacity": 0.6,
  "chord.showValues": true,
  "chord.opacity": 1
}
```

```bash
curl --location 'https://render.imejis.io/v1/{{YOUR_DESIGN_ID}}' \
--header 'dma-api-key: {{YOUR_API_KEY}}' \
--header 'Content-Type: application/json' \
--data '{
    "chord.links": [
        {
            "source": "North",
            "target": "South",
            "value": 40
        },
        {
            "source": "North",
            "target": "East",
            "value": 25
        },
        {
            "source": "North",
            "target": "West",
            "value": 15
        },
        {
            "source": "South",
            "target": "East",
            "value": 30
        },
        {
            "source": "South",
            "target": "West",
            "value": 20
        },
        {
            "source": "East",
            "target": "West",
            "value": 22
        }
    ],
    "chord.padAngle": 2,
    "chord.ribbonOpacity": 0.6,
    "chord.showValues": true,
    "chord.opacity": 1
}'
```

`{{YOUR_DESIGN_ID}}` and `{{YOUR_API_KEY}}` are placeholders: first create
the design in your account (paste the sample design JSON above into the
editor at https://app.imejis.io, or create it programmatically via the
imejis MCP server's `create_design` + `update_design` tools), then render
it with the design's id and one of your API keys.

Agents: the MCP server at https://api.imejis.io/api/mcp exposes this same
catalog as structured data via the `list_component_types` tool (property
kinds, allowed values, bounds, ready-to-use sample designs).

## Related

- [Chord Diagram component](https://www.imejis.io/components/chord.md) — full reference and FAQs
- [Thin arcs](https://www.imejis.io/components/chord/thin.md) — Slim group arcs that put the emphasis on the ribbons.
- [Dark](https://www.imejis.io/components/chord/dark.md) — A vivid chord diagram on a dark card for social and dashboards.