---
title: "Chord Diagram Image API — Relationship & flow diagrams | Imejis"
description: "Generate chord diagram images — entities on a circle with ribbons sized by relationship strength — for flows and many-to-many connections, set on every API call. Start free with Imejis."
url: "https://www.imejis.io/components/chord"
---

# Chord Diagram Image API — Relationship & flow diagrams | Imejis

A chord diagram — entities arranged on a circle with ribbons whose thickness shows the strength of each relationship. Built for flows and many-to-many connections.

## Use cases

- Migration / trade flows between regions or countries
- Cross-team or cross-product interaction maps
- Referral / co-occurrence relationships
- Any many-to-many connection summary

## Authoring notes

- links is [{ source, target, value }] — group names are matched by string; value sets ribbon thickness.
- Keep to 3–8 groups so the circle stays readable; self-relationships (source == target) are skipped.
- Use a square-ish box so the circle stays round; give the outer labels room.
- Set groups[] colors or a colors palette to brand the arcs; ribbons take the source color.

## 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)". |

## Sample design JSON

```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
      }
    }
  ]
}
```

## Examples

### Region migration flows

Movement between four regions, ribbons sized by volume.

API overrides that reproduce this example:

```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.showValues": true
}
```

### Team interactions

How often five teams collaborate, as a connection map.

API overrides that reproduce this example:

```json
{
  "chord.links": [
    {
      "source": "Eng",
      "target": "Design",
      "value": 34
    },
    {
      "source": "Eng",
      "target": "Product",
      "value": 40
    },
    {
      "source": "Design",
      "target": "Product",
      "value": 28
    },
    {
      "source": "Product",
      "target": "Sales",
      "value": 22
    },
    {
      "source": "Sales",
      "target": "Support",
      "value": 18
    },
    {
      "source": "Support",
      "target": "Eng",
      "value": 14
    }
  ],
  "chord.colors": [
    "#6366f1",
    "#22c55e",
    "#f59e0b",
    "#ec4899",
    "#0ea5e9"
  ]
}
```

## 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).

## Frequently Asked Questions

### How do I pass the relationships?

Send '<key>.links' as an array of { source, target, value } — group names are matched by string and each ribbon's thickness is proportional to its value.

### How are the groups arranged?

Groups are placed around the circle automatically, each arc sized to the group's total relationship weight; order and colors can be pinned via groups[].

### Can I color the arcs and ribbons?

Pass a colors palette or per-group colors via groups[]; ribbons take their source group’s color at ribbonOpacity.

### Can I show the totals?

Enable showValues to append each group’s total relationship weight to its label; valueFormat controls the number style.

## Variants

- [Thin arcs](https://www.imejis.io/components/chord/thin.md) — Slim group arcs that put the emphasis on the ribbons.
- [Custom palette](https://www.imejis.io/components/chord/palette.md) — Brand the arcs with your own colors.
- [Dark](https://www.imejis.io/components/chord/dark.md) — A vivid chord diagram on a dark card for social and dashboards.

All components: https://www.imejis.io/components.md