Add Aden to your website

Your site reads from Aden, so a new release, a sold-out show or a news post shows up there without anyone editing the site.

The site feed

One public address returns what your Aden profile already shows, as JSON:

https://aden.space/api/v1/public/sites/<handle>

Your handle is the part after @ in your profile address (aden.space/@stripes → stripes). On Team → API, the arrow beside Open in ChatGPT has Copy feed URL.

What's in it

{
    "data": {
        "artist": {
            "name": "Stripes",
            "slug": "stripes",
            "bio": "…",
            "genres": ["Electronic"],
            "city": "Antwerp",
            "country": "BE",
            "url": "https://aden.space/@stripes",
            "imageUrl": "https://…",
            "bannerUrl": "https://…"
        },
        "links": [{ "platform": "spotify", "url": "https://…" }],
        "shows": [
            {
                "id": 81,
                "name": "Stripes live",
                "date": "2026-11-21",
                "startTime": "21:00:00",
                "venue": "Trix",
                "city": "Antwerp",
                "country": "BE",
                "tour": null,
                "ticketUrl": "https://…",
                "url": "https://aden.space/@stripes/events/…",
                "imageUrl": "https://…",
                "soldOut": false,
                "cancelled": false
            }
        ],
        "releases": [
            {
                "id": 412,
                "kind": "track",
                "title": "Night Bus",
                "releaseDate": "2026-10-03",
                "coverUrl": "https://…",
                "url": "https://aden.space/@stripes/track/night-bus"
            }
        ],
        "posts": [
            {
                "id": 9,
                "title": "New single out",
                "excerpt": "…",
                "date": "2026-10-03",
                "imageUrl": "https://…",
                "url": "https://aden.space/@stripes/posts/…"
            }
        ]
    }
}

• shows: the next 20, today included. releases: the newest 12 tracks and 12 albums, newest first. posts: the latest 6.
• Each release url opens its Aden page, with every streaming link.
• Only public things appear: a show marked busy, an unreleased track or a draft post never does. Hide your picture on public pages and imageUrl is null.
• Image links never expire, so you can cache the feed as long as you like.

Use it

<ul id="aden-releases"></ul>
<script>
    fetch('https://aden.space/api/v1/public/sites/stripes')
        .then((res) => res.json())
        .then(({ data }) => {
            const list = document.getElementById('aden-releases')
            for (const release of data.releases) {
                const item = document.createElement('li')
                const link = document.createElement('a')
                link.href = release.url
                link.textContent = release.title
                item.append(link)
                list.append(item)
            }
        })
</script>

Changes reach the feed within about five minutes. Fetching more often than that returns the same answer, and one address that asks for more than 60 uncached feeds a minute gets a 429.

Private data with an API key

An API key reads your team's own data: the whole catalogue, unreleased tracks, milestones, tasks, contacts. It belongs on a server, never in a web page.

ADEN_API_KEY=aden_…
ADEN_TEAM_ID=216

const aden = async (path: string) => {
    const res = await fetch(`https://aden.space/api/v1${path}`, {
        headers: { authorization: `Bearer ${process.env.ADEN_API_KEY}` },
        next: { revalidate: 300 },
    })
    if (!res.ok) throw new Error(`Aden answered ${res.status}`)
    return res.json()
}

export const Catalogue = async () => {
    const { data: tracks, total } = await aden(
        `/tracks?teamId=${process.env.ADEN_TEAM_ID}&limit=50`
    )
    return (
        <section>
            <h2>{total} tracks</h2>
            <ul>
                {tracks.map((track) => (
                    <li key={track.id}>{track.title}</li>
                ))}
            </ul>
        </section>
    )
}

What a key can reach

A key belongs to one team and only ever reaches that team's data. It can call:

Most also have GET /<resource>/:id for one item. A Read & write key can also create and change milestones, tasks, contacts, webhooks and app data. Uploading audio, creating tracks and adding collaborators happen in Aden, by a signed-in member.

Every other endpoint answers a key with 403 endpoint_not_allowed. The API reference lists each endpoint's fields.

Limits

All of a team's keys share these. Every keyed response carries X-RateLimit-Remaining and X-RateLimit-Reset; a 429 adds Retry-After. Cache what you read: a site that fetches on every page view runs out fast. See Rate limits.

Errors

Error bodies hold the code in error, and most add a message that says what happened.

Keep keys safe

• One key per site or script, named after it, so you can revoke one without breaking the rest.
• Read only unless the code writes.
• Revoke a key on Team → API the moment you suspect it leaked. It stops working within a minute.