Introduction

This documentation aims to provide all the information you need to work with our API.

Base URL

https://crystal-rss.de

Authenticating requests

This API is authenticated by sending an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting your dashboard and clicking Generate API token.

Categories

API methods for managing categories

Display a listing of the resource.

requires authentication

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/categories"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://crystal-rss.de/api/v1/categories',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, success):


[
    {
        "id": 1,
        "user_id": 1,
        "name": "Technology",
        "created_at": "2021-07-19T16:46:51.000000Z",
        "updated_at": "2021-08-22T12:26:11.000000Z",
        "feeds_count": 8
    },
    {
        "id": 2,
        "user_id": 1,
        "name": "Poetry",
        "created_at": "2021-07-19T16:46:51.000000Z",
        "updated_at": "2021-08-22T12:26:11.000000Z",
        "feeds_count": 3
    }
]

Received response:

Request failed with error:

Store a newly created resource in storage.

requires authentication

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/categories"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "labore"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://crystal-rss.de/api/v1/categories',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'labore',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, success):


{
    "id": 3,
    "user_id": 1,
    "name": "Blogs",
    "created_at": "2021-07-19T16:46:51.000000Z",
    "updated_at": "2021-08-22T12:26:11.000000Z",
    "feeds_count": 0
}

Received response:

Request failed with error:

Display the specified resource.

requires authentication

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/categories/1"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://crystal-rss.de/api/v1/categories/1',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, success):


{
    "id": 1,
    "user_id": 1,
    "name": "Technology",
    "created_at": "2021-07-19T16:46:51.000000Z",
    "updated_at": "2021-08-22T12:26:11.000000Z",
    "feeds_count": 8
}

Received response:

Request failed with error:

Update the specified resource in storage.

requires authentication

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/categories/1"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "possimus"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://crystal-rss.de/api/v1/categories/1',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'possimus',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, success):


[{
 "id": 1,
 "user_id": 1,
 "name": "Tech & IT",
 "created_at": "2021-07-19T16:46:51.000000Z",
 "updated_at": "2021-08-23T12:26:11.000000Z",
 "feeds_count": 8
}

Received response:

Request failed with error:

Remove the specified resource from storage.

requires authentication

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/categories/1"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->delete(
    'https://crystal-rss.de/api/v1/categories/1',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, success):

{}

Received response:

Request failed with error:

Feeds

API methods for managing feeds

Mark all unread feed items as read.

requires authentication

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/feeds/mark_all_as_read"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "PUT",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://crystal-rss.de/api/v1/feeds/mark_all_as_read',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, success):

{}

Received response:

Request failed with error:

Display a listing of the resource.

requires authentication

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/feeds"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://crystal-rss.de/api/v1/feeds',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, success):


[
    {
        "id": 1,
        "user_id": 1,
        "category_id": 1,
        "feed_url": "http://www.example.com/feed",
        "site_url": "http://www.example.com",
        "favicon_url": "http://www.example.com/favicon.ico",
        "name": "Example feed",
        "last_checked_at": "2022-01-12T21:18:15.000000Z",
        "created_at": "2021-07-19T16:46:51.000000Z",
        "updated_at": "2021-08-22T12:26:11.000000Z",
        "feed_items_count": 7,
        "category": {
            "id": 1,
            "user_id": 1,
            "name": "Example category",
            "created_at": "2021-09-23T19:11:01.000000Z",
            "updated_at": "2021-09-23T19:11:01.000000Z"
        }
    },
    {
        "id": 1,
        "user_id": 1,
        "category_id": 2,
        "feed_url": "http://www.example.com/feed",
        "site_url": "http://www.example.com",
        "favicon_url": "http://www.example.com/favicon.ico",
        "name": "Example feed",
        "last_checked_at": "2022-01-12T21:18:15.000000Z",
        "created_at": "2021-07-19T16:46:51.000000Z",
        "updated_at": "2021-08-22T12:26:11.000000Z",
        "feed_items_count": 7,
        "category": {
            "id": 1,
            "user_id": 1,
            "name": "Example category",
            "created_at": "2021-09-23T19:11:01.000000Z",
            "updated_at": "2021-09-23T19:11:01.000000Z"
        }
    }
]

Received response:

Request failed with error:

Store a newly created resource in storage.

requires authentication

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/feeds"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "category_id": 5,
    "feed_url": "ipsam",
    "site_url": "ipsum",
    "name": "non",
    "language": "architecto"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://crystal-rss.de/api/v1/feeds',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'category_id' => 5,
            'feed_url' => 'ipsam',
            'site_url' => 'ipsum',
            'name' => 'non',
            'language' => 'architecto',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, success):


{
    "id": 1,
    "user_id": 1,
    "category_id": 1,
    "feed_url": "http://www.example.com/feed",
    "site_url": "http://www.example.com",
    "favicon_url": "http://www.example.com/favicon.ico",
    "name": "Example feed",
    "last_checked_at": "2022-01-12T21:18:15.000000Z",
    "created_at": "2021-07-19T16:46:51.000000Z",
    "updated_at": "2021-08-22T12:26:11.000000Z",
    "feed_items_count": 7,
    "category": {
        "id": 1,
        "user_id": 1,
        "name": "Example category",
        "created_at": "2021-09-23T19:11:01.000000Z",
        "updated_at": "2021-09-23T19:11:01.000000Z"
    }
}

Received response:

Request failed with error:

Request

POST api/v1/feeds

Body Parameters

category_id integer

The ID of the category.

feed_url string

The URL of the feed.

site_url string

The URL of the website.

name string

THe name of the feed.

language string optional

Display the specified resource.

requires authentication

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/feeds/1"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://crystal-rss.de/api/v1/feeds/1',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, success):


{
    "id": 1,
    "user_id": 1,
    "category_id": 1,
    "feed_url": "http://www.example.com/feed",
    "site_url": "http://www.example.com",
    "favicon_url": "http://www.example.com/favicon.ico",
    "name": "Example feed",
    "last_checked_at": "2022-01-12T21:18:15.000000Z",
    "created_at": "2021-07-19T16:46:51.000000Z",
    "updated_at": "2021-08-22T12:26:11.000000Z",
    "feed_items_count": 7,
    "category": {
        "id": 1,
        "user_id": 1,
        "name": "Example category",
        "created_at": "2021-09-23T19:11:01.000000Z",
        "updated_at": "2021-09-23T19:11:01.000000Z"
    }
}

Received response:

Request failed with error:

Update the specified resource in storage.

requires authentication

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/feeds/1"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "category_id": 8,
    "feed_url": "quae",
    "site_url": "velit",
    "name": "nisi",
    "language": "animi"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://crystal-rss.de/api/v1/feeds/1',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'category_id' => 8,
            'feed_url' => 'quae',
            'site_url' => 'velit',
            'name' => 'nisi',
            'language' => 'animi',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, success):


[{
 "id": 1,
 "user_id": 1,
 "category_id": 1,
 "feed_url": "http://www.example.com/feed",
 "site_url": "http://www.example.com",
 "favicon_url": "http://www.example.com/favicon.ico",
 "name": "Example feed",
 "last_checked_at": "2022-01-12T21:18:15.000000Z",
 "created_at": "2021-07-19T16:46:51.000000Z",
 "updated_at": "2021-08-22T12:26:11.000000Z",
 "feed_items_count": 7,
 "category": {
  "id": 1,
  "user_id": 1,
  "name": "Example category",
  "created_at": "2021-09-23T19:11:01.000000Z",
  "updated_at": "2021-09-23T19:11:01.000000Z"
 }
}

Received response:

Request failed with error:

Request

PUT api/v1/feeds/{id}

PATCH api/v1/feeds/{id}

URL Parameters

id integer

The ID of the feed.

Body Parameters

category_id integer

The ID of the category.

feed_url string

The URL of the feed.

site_url string

The URL of the website.

name string

THe name of the feed.

language string optional

Remove the specified resource from storage.

requires authentication

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/feeds/1"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->delete(
    'https://crystal-rss.de/api/v1/feeds/1',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, success):

{}

Received response:

Request failed with error:

Miscellaneous

API methods for basic information

Healthcheck

Check that the service is up. If everything is okay, you'll get a 200 OK response.

Otherwise, the request will fail with a 400 error, and a response listing the failed services.

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/health_check"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://crystal-rss.de/api/v1/health_check',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (400, Service is unhealthy):


{
    "status": false,
    "services": {
        "database": false
    }
}

Example response (200):

Show headers

cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 59
access-control-allow-origin: *


{
    "status": true,
    "services": {
        "database": true
    }
}

Received response:

Request failed with error:

Response

Response Fields

status boolean

The status of this API (true or false).

services object

Map of each downstream service and their status (true or false).

Retrieve own user

requires authentication

Example request:

const url = new URL(
    "https://crystal-rss.de/api/v1/user"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://crystal-rss.de/api/v1/user',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200, success):


{
    "id": 1,
    "name": "John Doe",
    "email": "john_doe@test.com",
    "email_verified_at": "2021-07-19T16:52:07.000000Z",
    "current_team_id": null,
    "profile_photo_path": "profile-photos/tQoWDCXYOOOK15OykHUBLnyrTvB76laGnIAwtaj8.jpg",
    "created_at": "2021-07-19T16:46:51.000000Z",
    "updated_at": "2021-08-22T12:26:11.000000Z",
    "profile_photo_url": "/storage/profile-photos/tQoWDCXYOOOK15OykHUBLnyrTvB76laGnIAwtaj8.jpg"
}

Received response:

Request failed with error:

Introduction

Authenticating requests

Categories

Display a listing of the resource.

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Store a newly created resource in storage.

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Body Parameters

Display the specified resource.

Request Try it out ⚡ Cancel 🛑 Send Request 💥

URL Parameters

Update the specified resource in storage.

Request Try it out ⚡ Cancel 🛑 Send Request 💥

URL Parameters

Body Parameters

Remove the specified resource from storage.

Request Try it out ⚡ Cancel 🛑 Send Request 💥

URL Parameters

Feeds

Mark all unread feed items as read.

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Display a listing of the resource.

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Store a newly created resource in storage.

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Body Parameters

Display the specified resource.

Request Try it out ⚡ Cancel 🛑 Send Request 💥

URL Parameters

Update the specified resource in storage.

Request Try it out ⚡ Cancel 🛑 Send Request 💥

URL Parameters

Body Parameters

Remove the specified resource from storage.

Request Try it out ⚡ Cancel 🛑 Send Request 💥

URL Parameters

Miscellaneous

Healthcheck

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Response

Response Fields

Retrieve own user

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request