# API Overview
Source: https://docs.aden.space/docs/developers/api

The HTTP surface that powers Aden. REST, JSON, OpenAPI 3.1.
The Aden API is a versioned REST API mounted at
`https://www.aden.space/api/v1`. Every endpoint the Aden web and mobile apps
call is available to you too.

## Base URL [#base-url]

```
https://www.aden.space/api/v1
```

Self-hosted deployments expose the API at the same `/api/v1` prefix under
your own domain. Point the SDK at it with `baseUrl`.

## OpenAPI spec [#openapi-spec]

The canonical source of truth lives at
[`/api/v1/openapi/json`](https://www.aden.space/api/v1/openapi/json). It's regenerated
from the server on every deploy. The SDK types are derived from the same
definitions, so the [SDK](/docs/developers/sdk) and the OpenAPI spec can never drift.

See the [Reference](/docs/developers/api/reference) for per-endpoint details rendered
from that spec.

## Resources [#resources]

| Tag          | What it covers                                              |
| ------------ | ----------------------------------------------------------- |
| Auth         | Session info for logged-in users (`auth.me`)                |
| Tracks       | Tracks, versions, final masters, covers                     |
| Albums       | Albums and their tracks                                     |
| Teams        | Team info, members, roles                                   |
| Contacts     | Collaborators, contact groups                               |
| Sessions     | Studio sessions. Shared workspaces                          |
| Chat         | Threads, messages, read receipts                            |
| Calendar     | Milestones, releases, posts, todos, sessions on a timeline  |
| Campaigns    | Release campaigns                                           |
| Tours        | Tour dates and venues                                       |
| Playlists    | Playlist placements and pitches                             |
| Posts        | Social post planning                                        |
| Stats        | Streaming and follower stats                                |
| Testimonials | Public testimonials                                         |
| User         | The authenticated user's profile, identities, notifications |
| Health       | `GET /health`: public liveness check                        |

## Request format [#request-format]

* Content type: `application/json` for bodies, `multipart/form-data` for
  uploads.
* Query params for filters and pagination (`limit`, `offset`, `teamId`).
* Path params for entity IDs (`/tracks/:id`).
* Dates are ISO-8601 strings, IDs are integers unless noted.

## Response format [#response-format]

Success bodies are the entity or array of entities directly, no wrapper.
Error bodies are `{ "error": string }`. See [Errors](/docs/developers/sdk/errors) for
status code conventions.

## CORS [#cors]

The API sends permissive CORS headers. You can call it directly from a
browser, but **don't** ship API keys to the browser. Use
[Supabase tokens](/docs/developers/api/authentication#supabase-session-tokens) for
user-facing apps.

## Next [#next]

<Cards>
  <Card title="Authentication" href="/docs/developers/api/authentication" />

  <Card title="Rate limits" href="/docs/developers/api/rate-limits" />

  <Card title="Reference" href="/docs/developers/api/reference" />

  <Card title="SDK Quickstart" href="/docs/developers/sdk/quickstart" />
</Cards>