# Subliss API

The Subliss API reads public subliminals and creator profiles, the same tracks anyone can find on Discover and on creator pages. Use it to post your new subliminals somewhere else when you publish them, or to find tracks by title, category or creator.

It only reads. It never returns private subliminals, affirmations or account details, so a key that leaks exposes nothing private.

- Base address: `https://api.subliss.app/v1`
- OpenAPI file: https://subliss.app/developers/openapi.json
- Version 1, November 2026

## Get a key

1. Sign in at https://subliss.app and open Account.
2. Under Developer keys, choose Make a key and give it a name, such as Make.
3. Copy the key straight away. Subliss stores only a scrambled copy, so it shows the key once.

A key starts with `sbl_` and has 64 characters after that. One account can hold 5 keys at once. Revoke a key under Account and anything using it stops working straight away.

## Send the key

Send the key in the `Authorization` header of every request:

```
curl https://api.subliss.app/v1/me \
  -H "Authorization: Bearer sbl_your_key"
```

Never put the key in an address. Addresses end up in logs, so the API refuses any request with a key in the address (`key_in_url`). If that happens, revoke the key and make a new one.

## Limits

Each key can make 60 requests a minute. Past that the API answers `429` with a `Retry-After` header that says how many seconds to wait.

## Endpoints

### GET /me

The account the key belongs to. Use it to check a key works.

```json
{
  "handle": "maya",
  "name": "Maya",
  "url": "https://subliss.app/creator/maya"
}
```

### GET /tracks

Public subliminals, newest first.

| Parameter | What it does |
| --- | --- |
| `search` | Words to find in the title, up to 100 characters. |
| `category` | A category key or label from `/categories`, such as `healing` or `Self-worth`. |
| `creator` | A creator's handle, with or without `@`. |
| `sort` | `newest` (the default, by publish date) or `popular` (by plays). |
| `limit` | How many to return, 1 to 100. The default is 20. |
| `offset` | How many to skip, 0 to 10000. Use `next_offset` from the last page. |
| `published_after` | A date and time such as `2026-11-01T09:00:00Z`. Only subliminals published at that moment or later come back. |

```
curl "https://api.subliss.app/v1/tracks?category=healing&limit=2" \
  -H "Authorization: Bearer sbl_your_key"
```

```json
{
  "tracks": [
    {
      "id": "0b9f3c2e-5a1d-4c7e-9f00-6d2b8a4e1c57",
      "title": "Calm mornings",
      "url": "https://subliss.app/creator/maya/calm-mornings",
      "categories": ["Healing", "Self-worth"],
      "duration_seconds": 300,
      "play_count": 41,
      "like_count": 6,
      "published_at": "2026-10-31T16:45:05Z",
      "creator": {
        "handle": "maya",
        "name": "Maya",
        "url": "https://subliss.app/creator/maya"
      }
    }
  ],
  "has_more": true,
  "next_offset": 2
}
```

`has_more` says whether another page follows. `next_offset` is the `offset` for that page, or `null` on the last one.

### GET /tracks/{id}

One public subliminal, in the same shape as an item in `/tracks`. A subliminal that is private, unlisted or deleted answers `404`.

### GET /creators/{handle}

A creator's public profile.

```json
{
  "handle": "maya",
  "name": "Maya",
  "url": "https://subliss.app/creator/maya",
  "avatar_url": null,
  "bio": "Sleep tracks, mostly.",
  "track_count": 12,
  "total_play_count": 530,
  "follower_count": 18,
  "joined_at": "2026-05-02T09:12:00Z"
}
```

### GET /categories

Every category a subliminal can have, each as a `key` and a `label`, such as `wellbeing` and Self-worth. Filter `/tracks` by either.

## Errors

Every error has the same shape:

```json
{
  "error": {
    "code": "invalid_key",
    "message": "That key is not a Subliss key, or it has been revoked.",
    "docs": "https://subliss.app/developers/index.html"
  }
}
```

The `code` stays the same, so check that rather than the message.

| Status | Code | What it means |
| --- | --- | --- |
| 400 | `key_in_url` | The key was in the address. Revoke it and make a new one. |
| 400 | `invalid_limit`, `invalid_offset`, `invalid_sort`, `invalid_category`, `invalid_published_after` | A parameter is out of range. The message says which values work. |
| 401 | `missing_key` | No `Authorization` header. |
| 401 | `invalid_key` | The key is not a Subliss key, or it has been revoked. |
| 404 | `track_not_found`, `creator_not_found`, `not_found` | Nothing public matches. |
| 405 | `method_not_allowed` | The API only reads. Send `GET`. |
| 429 | `rate_limited` | 60 requests this minute. Wait for `Retry-After` seconds. |
| 500 | `server_error` | Something went wrong on our side. Try again in a minute. |

## Help

Write to hello@subliss.app or use https://subliss.app/contact.