Introduction

Kbin is a reddit-like content aggregator and micro-blogging platform for the fediverse.

This is a very early beta version, and a lot of features are currently broken or in active development, such as federation.

Magazines

Get All magazines

curl "https://dev.karab.in/api/magazines"

use Symfony\Contracts\HttpClient\HttpClientInterface;

$response = $this->client->request(
            'GET',
            'https://dev.karab.in/api/magazines'
        );

$entries = $response->getContent();

import kbin from 'kbin-js-client';

let entries = kbin.magazines.get();

{
  "@context": "/api/contexts/magazine",
  "@id": "/api/magazines",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/api/magazines/rust",
      "@type": "magazine",
      "user": {
        "@id": "/api/users/ernest",
        "@type": "user",
        "username": "ernest"
      },
      "cover": {
        "@id": "/api/images/56",
        "@type": "image",
        "filePath": "08/8e/088e62b44d8a946015e2fb1378ef6866c3e1b059107b67e7391d7b1c7ca7c40b.jpg",
        "width": 2048,
        "height": 1024
      },
      "name": "rust",
      "title": "rust",
      "description": null,
      "rules": null,
      "subscriptionsCount": 1,
      "entryCount": 1,
      "entryCommentCount": 0,
      "postCount": 0,
      "postCommentCount": 0,
      "isAdult": false
    }
  ],
  "hydra:totalItems": 13
}

This endpoint retrieves all magazines.

HTTP Request

GET http://dev.karab.in/api/magazines

Query Parameters

Parameter	Default	Required	Description
page	1	false

Response

Field	Type	Nullable
@id	string	false
@type	string	false
user	object	false
cover	object	true
name	string	false
title	string	false
description	string	true
rules	string	true
subscriptionsCount	int	false
entryCount	int	false
entryCommentCount	int	false
postCount	int	false
postCommentCount	int	false
isAdult	bool	fals

Get Single Magazine

curl "https://dev.karab.in/api/magazines/{magazine_name}"

use Symfony\Contracts\HttpClient\HttpClientInterface;

$response = $this->client->request(
            'GET',
            'https://dev.karab.in/api/magazines/{magazine_name}'
        );

$entries = $response->getContent();

import kbin from 'kbin-js-client';

let entries = kbin.magazines.get({magazine_name});

{
  "@context": "/api/contexts/magazine",
  "@id": "/api/magazines/rust",
  "@type": "magazine",
  "user": {
    "@id": "/api/users/ernest",
    "@type": "user",
    "username": "ernest",
    "avatar": []
  },
  "cover": {
    "@id": "/api/images/56",
    "@type": "image",
    "filePath": "08/8e/088e62b44d8a946015e2fb1378ef6866c3e1b059107b67e7391d7b1c7ca7c40b.jpg",
    "width": 2048,
    "height": 1024
  },
  "name": "rust",
  "title": "rust",
  "description": null,
  "rules": null,
  "subscriptionsCount": 1,
  "entryCount": 1,
  "entryCommentCount": 0,
  "postCount": 0,
  "postCommentCount": 0,
  "isAdult": false
}

This endpoint retrieves a specific magazine.

HTTP Request

GET http://dev.karab.in/api/magazines/{magazine_name}

HTTP Request

Parameter	Type	Description
magazine_name	string	The name of magazine

Response

Field	Type	Nullable
@id	string	false
@type	string	false
user	object	false
cover	object	true
name	string	false
title	string	false
description	string	true
rules	string	true
subscriptionsCount	int	false
entryCount	int	false
entryCommentCount	int	false
postCount	int	false
postCommentCount	int	false
isAdult	bool	fals

Entries

Get All Entries

curl "https://dev.karab.in/api/entries"

use Symfony\Contracts\HttpClient\HttpClientInterface;

$response = $this->client->request(
            'GET',
            'https://dev.karab.in/api/entries'
        );

$entries = $response->getContent();

import kbin from 'kbin-js-client';

let entries = kbin.entries.get();

{
  "@context": "/api/contexts/entry",
  "@id": "/api/entries",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/api/entries/39",
      "@type": "entry",
      "magazine": {
        "@id": "/api/magazines/polska",
        "@type": "magazine",
        "name": "polska"
      },
      "user": {
        "@id": "/api/users/ernest",
        "@type": "user",
        "username": "ernest"
      },
      "image": {
        "@id": "/api/images/62",
        "@type": "image",
        "filePath": "71/d5/71d5e6d075b8861a8a675c817f0592e40f65cbe3d5e4dd56c9eb4e52a9217a8c.jpg",
        "width": 480,
        "height": 360
      },
      "domain": {
        "@id": "/api/domains/4",
        "@type": "domain",
        "name": "youtube.com"
      },
      "title": "Concert of the 1st Prize Laureate of the 18th Chopin Competition – BRUCE (XIAOYU) LIU",
      "url": "https://www.youtube.com/watch?v=0ie831U-sCU",
      "comments": 0,
      "uv": 0,
      "dv": 0,
      "isAdult": false,
      "views": 5,
      "score": 0,
      "visibility": "visible",
      "createdAt": "2021-10-26T19:15:57+00:00",
      "lastActive": "2021-10-26T19:15:57+00:00",
      "id": 39,
      "type": "link"
    }
  ],
  "hydra:totalItems": 196,
  "hydra:view": {
    "@id": "/api/entries.jsonld?page=1",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/api/entries.jsonld?page=1",
    "hydra:last": "/api/entries.jsonld?page=8",
    "hydra:next": "/api/entries.jsonld?page=2"
  }
}

This endpoint retrieves all entries.

HTTP Request

GET http://dev.karab.in/api/entries

Query Parameters

Parameter	Default	Required	Description
page	1	false
magazine	null	false	If the magazine does not exist, returns a list of all magazines.
sort	hot	false	top / hot / newest / active / newest
time	all	false	all / 6hours / 12hours / day / week / month / year

Response

Field	Type	Nullable	Description
@id	string	false
@type	string	false
magazine	object	false
user	object	false
image	object	true
domain	object	true
title	string	false
url	string	true
comments	int	false
uv	int	false
dv	int	false
isAdult	bool	false
views	int	false
score	int	false
visibility	string	false	visible / trashed
createdAt	string	false
lastActive	string	false
id	int	false
type	string	false	link / article / video / image

Get Single Entry

curl "https://dev.karab.in/api/entries/{id}"

use Symfony\Contracts\HttpClient\HttpClientInterface;

$response = $this->client->request(
            'GET',
            'https://dev.karab.in/api/entries/{id}'
        );

$entries = $response->getContent();

import kbin from 'kbin-js-client';

let entries = kbin.entries.get({id});

{
  "@context": "/api/contexts/entry",
  "@id": "/api/entries/39",
  "@type": "entry",
  "magazine": {
    "@id": "/api/magazines/polska",
    "@type": "magazine",
    "name": "polska"
  },
  "user": {
    "@id": "/api/users/ernest",
    "@type": "user",
    "username": "ernest",
    "avatar": {
      "@id": "/api/images/54",
      "@type": "image",
      "filePath": "89/bf/89bf6b16d2516c0756275aacbc88f443c45076c554e3e19b132c3ffd9e8356ee.jpg",
      "width": 978,
      "height": 931
    }
  },
  "image": {
    "@id": "/api/images/62",
    "@type": "image",
    "filePath": "71/d5/71d5e6d075b8861a8a675c817f0592e40f65cbe3d5e4dd56c9eb4e52a9217a8c.jpg",
    "width": 480,
    "height": 360
  },
  "domain": {
    "@id": "/api/domains/4",
    "@type": "domain",
    "name": "youtube.com",
    "entryCount": 11
  },
  "title": "Concert of the 1st Prize Laureate of the 18th Chopin Competition – BRUCE (XIAOYU) LIU",
  "url": "https://www.youtube.com/watch?v=0ie831U-sCU",
  "body": null,
  "comments": 0,
  "uv": 0,
  "dv": 0,
  "isAdult": false,
  "views": 5,
  "score": 0,
  "visibility": "visible",
  "createdAt": "2021-10-26T19:15:57+00:00",
  "lastActive": "2021-10-26T19:15:57+00:00",
  "id": 39,
  "type": "link"
}

This endpoint retrieves a specific entry.

HTTP Request

GET http://dev.karab.in/api/entries/{id}

HTTP Request

Parameter	Type	Description
id	int	The ID of the entry to retrieve

Response

Field	Type	Nullable	Description
@id	string	false
@type	string	false
magazine	object	false
user	object	false
image	object	true
domain	object	true
title	string	false
url	string	true
body	string	true
comments	int	false
uv	int	false
dv	int	false
isAdult	bool	false
views	int	false
score	int	false
visibility	string	false	visible / trashed
createdAt	string	false
lastActive	string	false
id	int	false
type	string	false	link / article / video / image

Get Entry Comments

curl "https://dev.karab.in/api/entries/{id}/comments"

use Symfony\Contracts\HttpClient\HttpClientInterface;

$response = $this->client->request(
            'GET',
            'https://dev.karab.in/api/entries/{id}/comments'
        );

$entries = $response->getContent();

import kbin from 'kbin-js-client';

let entries = kbin.entries.get({id}).comments;

{
  "@context": "/api/contexts/entry_comment",
  "@id": "/api/entry_comments",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/api/entry_comments/1",
      "@type": "entry_comment",
      "magazine": {
        "@id": "/api/magazines/karabin",
        "@type": "magazine",
        "name": "karabin"
      },
      "user": {
        "@id": "/api/users/ernest",
        "@type": "user",
        "username": "ernest",
        "avatar": {
          "@id": "/api/images/54",
          "@type": "image",
          "filePath": "89/bf/89bf6b16d2516c0756275aacbc88f443c45076c554e3e19b132c3ffd9e8356ee.jpg",
          "width": 978,
          "height": 931
        }
      },
      "entry": {
        "@id": "/api/entries/1",
        "@type": "entry",
        "title": "karab.in - polska instancja /kbin",
        "id": 1
      },
      "parent": null,
      "root": null,
      "image": null,
      "body": "https://kbin.info jest otwartym portalem agregującym treści (podobnym do reddita) oraz platformą do mikroblogowania przeznaczoną dla fediwersum.",
      "uv": 0,
      "dv": 0,
      "createdAt": "2021-09-12T08:00:27+00:00",
      "lastActive": "2021-10-25T15:35:28+00:00",
      "id": 1
    }
  ],
  "hydra:totalItems": 1
}

This endpoint retrieves entry comments.

HTTP Request

GET http://dev.karab.in/api/entries/{id}/comments

HTTP Request

Parameter	Type	Description
id	int	The ID of the entry

Response

Field	Type	Nullable
@id	string	false
@type	string	false
magazine	object	false
user	object	false
parent	object	true
root	object	true
image	object	true
body	string	false
uv	int	false
dv	int	false
createdAt	string	false
lastActive	string	false
id	int	false

Comments

Get All comments

curl "https://dev.karab.in/api/entry_comments"

use Symfony\Contracts\HttpClient\HttpClientInterface;

$response = $this->client->request(
            'GET',
            'https://dev.karab.in/api/entry_comments'
        );

$entries = $response->getContent();

import kbin from 'kbin-js-client';

let entries = kbin.comments.get();

{
  "@context": "/api/contexts/entry_comment",
  "@id": "/api/entry_comments",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/api/entry_comments/1",
      "@type": "entry_comment",
      "magazine": {
        "@id": "/api/magazines/karabin",
        "@type": "magazine",
        "name": "karabin"
      },
      "user": {
        "@id": "/api/users/ernest",
        "@type": "user",
        "username": "ernest",
        "avatar": {
          "@id": "/api/images/54",
          "@type": "image",
          "filePath": "89/bf/89bf6b16d2516c0756275aacbc88f443c45076c554e3e19b132c3ffd9e8356ee.jpg",
          "width": 978,
          "height": 931
        }
      },
      "entry": {
        "@id": "/api/entries/1",
        "@type": "entry",
        "title": "karab.in - polska instancja /kbin",
        "id": 1
      },
      "parent": null,
      "root": null,
      "image": null,
      "body": "Lorem ipsum",
      "uv": 0,
      "dv": 0,
      "createdAt": "2021-09-12T08:00:27+00:00",
      "lastActive": "2021-10-25T15:35:28+00:00",
      "id": 1
    }
  ],
  "hydra:totalItems": 196,
  "hydra:view": {
    "@id": "/api/entries.jsonld?page=1",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/api/entries.jsonld?page=1",
    "hydra:last": "/api/entries.jsonld?page=8",
    "hydra:next": "/api/entries.jsonld?page=2"
  }
}

This endpoint retrieves all comments.

HTTP Request

GET http://dev.karab.in/api/entry_comments

Query Parameters

Parameter	Default	Required	Description
page	1	false
magazine	null	false	If the magazine does not exist, returns a list of all magazines.
sort	hot	false	top / hot / newest / active / newest
time	all	false	all / 6hours / 12hours / day / week / month / year

Response

Field	Type	Nullable
@id	string	false
@type	string	false
magazine	object	false
user	object	false
parent	object	true
root	object	true
image	object	true
body	string	false
uv	int	false
dv	int	false
createdAt	string	false
lastActive	string	false
id	int	false

Get Single Comment

curl "https://dev.karab.in/api/entry_comments/{id}"

use Symfony\Contracts\HttpClient\HttpClientInterface;

$response = $this->client->request(
            'GET',
            'https://dev.karab.in/api/entry_comments/{id}'
        );

$entries = $response->getContent();

import kbin from 'kbin-js-client';

let entries = kbin.comments.get({id});

{
  "@context": "/api/contexts/entry_comment",
  "@id": "/api/entry_comments/1",
  "@type": "entry_comment",
  "magazine": {
    "@id": "/api/magazines/karabin",
    "@type": "magazine"
  },
  "user": {
    "@id": "/api/users/ernest",
    "@type": "user"
  },
  "parent": null,
  "root": null,
  "image": null,
  "body": "Lorem ipsum.",
  "uv": 0,
  "dv": 0,
  "createdAt": "2021-09-12T08:00:27+00:00",
  "lastActive": "2021-10-25T15:35:28+00:00",
  "id": 1
}

This endpoint retrieves a specific comment.

HTTP Request

GET http://dev.karab.in/api/entry_comments/{id}

HTTP Request

Parameter	Type	Description
id	int	The ID of the comment to retrieve

Response

Field	Type	Nullable
@id	string	false
@type	string	false
magazine	object	false
user	object	false
parent	object	true
root	object	true
image	object	true
body	string	false
uv	int	false
dv	int	false
createdAt	string	false
lastActive	string	false
id	int	false

Posts

Get All posts

curl "https://dev.karab.in/api/posts"

use Symfony\Contracts\HttpClient\HttpClientInterface;

$response = $this->client->request(
            'GET',
            'https://dev.karab.in/api/posts'
        );

$entries = $response->getContent();

import kbin from 'kbin-js-client';

let entries = kbin.posts.get();

{
  "@context": "/api/contexts/post",
  "@id": "/api/posts",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/api/posts/1",
      "@type": "post",
      "magazine": {
        "@id": "/api/magazines/karabin",
        "@type": "magazine",
        "name": "karabin"
      },
      "user": {
        "@id": "/api/users/ernest",
        "@type": "user",
        "username": "ernest",
        "avatar": {
          "@id": "/api/images/54",
          "@type": "image",
          "filePath": "89/bf/89bf6b16d2516c0756275aacbc88f443c45076c554e3e19b132c3ffd9e8356ee.jpg",
          "width": 978,
          "height": 931
        }
      },
      "image": null,
      "body": "Lorem ipsum",
      "isAdult": false,
      "comments": 2,
      "uv": 0,
      "dv": 0,
      "score": 0,
      "visibility": "visible",
      "createdAt": "2021-09-08T13:00:28+00:00",
      "lastActive": "2021-09-16T06:59:32+00:00",
      "bestComments": [
        {
          "@id": "/api/post_comments/1",
          "@type": "post_comment",
          "user": {
            "@id": "/api/users/ernest",
            "@type": "user",
            "username": "ernest",
            "avatar": {
              "@id": "/api/images/54",
              "@type": "image",
              "filePath": "89/bf/89bf6b16d2516c0756275aacbc88f443c45076c554e3e19b132c3ffd9e8356ee.jpg",
              "width": 978,
              "height": 931
            }
          },
          "image": null,
          "body": "Lorem ipsum",
          "uv": 0,
          "createdAt": "2021-09-08T13:56:19+00:00",
          "lastActive": "2021-09-08T13:56:19+00:00",
          "id": 1
        },
        {
          "@id": "/api/post_comments/3",
          "@type": "post_comment",
          "user": {
            "@id": "/api/users/ernest",
            "@type": "user",
            "username": "ernest",
            "avatar": {
              "@id": "/api/images/54",
              "@type": "image",
              "filePath": "89/bf/89bf6b16d2516c0756275aacbc88f443c45076c554e3e19b132c3ffd9e8356ee.jpg",
              "width": 978,
              "height": 931
            }
          },
          "image": null,
          "body": "Lorem ipsum",
          "uv": 0,
          "createdAt": "2021-09-16T06:59:32+00:00",
          "lastActive": "2021-09-16T06:59:32+00:00",
          "id": 3
        }
      ],
      "id": 1
    }
  ],
  "hydra:totalItems": 196,
  "hydra:view": {
    "@id": "/api/entries.jsonld?page=1",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/api/entries.jsonld?page=1",
    "hydra:last": "/api/entries.jsonld?page=8",
    "hydra:next": "/api/entries.jsonld?page=2"
  }
}

This endpoint retrieves all posts.

HTTP Request

GET http://dev.karab.in/api/posts

Query Parameters

Parameter	Default	Required	Description
page	1	false
magazine	null	false	If the magazine does not exist, returns a list of all magazines.
sort	hot	false	top / hot / newest / active / newest
time	all	false	all / 6hours / 12hours / day / week / month / year

Response

Field	Type	Nullable
@id	string	false
@type	string	false
magazine	object	false
user	object	false
image	object	true
body	string	false
isAdult	bool	false
comments	int	false
uv	int	false
dv	int	false
score	int	false
visibility	int	false
createdAt	string	false
lastActive	string	false
bestComments	collection[reply]	false
id	int	false

Get Single Post

curl "https://dev.karab.in/api/posts/{id}"

use Symfony\Contracts\HttpClient\HttpClientInterface;

$response = $this->client->request(
            'GET',
            'https://dev.karab.in/api/posts/{id}'
        );

$entries = $response->getContent();

import kbin from 'kbin-js-client';

let entries = kbin.posts.get({id});

{
  "@context": "/api/contexts/post",
  "@id": "/api/posts/1",
  "@type": "post",
  "magazine": {
    "@id": "/api/magazines/karabin",
    "@type": "magazine",
    "name": "karabin"
  },
  "user": {
    "@id": "/api/users/ernest",
    "@type": "user",
    "username": "ernest",
    "avatar": {
      "@id": "/api/images/54",
      "@type": "image",
      "filePath": "89/bf/89bf6b16d2516c0756275aacbc88f443c45076c554e3e19b132c3ffd9e8356ee.jpg",
      "width": 978,
      "height": 931
    }
  },
  "image": null,
  "body": "LoremIpsum",
  "isAdult": false,
  "comments": 2,
  "uv": 0,
  "dv": 0,
  "score": 0,
  "visibility": "visible",
  "createdAt": "2021-09-08T13:00:28+00:00",
  "lastActive": "2021-09-16T06:59:32+00:00",
  "id": 1
}

This endpoint retrieves a specific post.

HTTP Request

GET http://dev.karab.in/api/post/{id}

HTTP Request

Parameter	Type	Description
id	int	The ID of the post to retrieve

Response

Field	Type	Nullable
@id	string	false
@type	string	false
magazine	object	false
user	object	false
parent	object	true
root	object	true
image	object	true
body	string	false
uv	int	false
dv	int	false
createdAt	string	false
lastActive	string	false
id	int	false

Get Post Replies

curl "https://dev.karab.in/api/posts/{id}/comments"

use Symfony\Contracts\HttpClient\HttpClientInterface;

$response = $this->client->request(
            'GET',
            'https://dev.karab.in/api/posts/{id}/comments'
        );

$entries = $response->getContent();

import kbin from 'kbin-js-client';

let entries = kbin.posts.get({id}).replies;

{
  "@context": "/api/contexts/post",
  "@id": "/api/posts",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/api/post_comments/1",
      "@type": "post_comment",
      "magazine": {
        "@id": "/api/magazines/karabin",
        "@type": "magazine",
        "name": "karabin"
      },
      "user": {
        "@id": "/api/users/ernest",
        "@type": "user",
        "username": "ernest",
        "avatar": {
          "@id": "/api/images/54",
          "@type": "image",
          "filePath": "89/bf/89bf6b16d2516c0756275aacbc88f443c45076c554e3e19b132c3ffd9e8356ee.jpg",
          "width": 978,
          "height": 931
        }
      },
      "parent": null,
      "body": "test",
      "uv": 0,
      "createdAt": "2021-09-08T13:56:19+00:00",
      "lastActive": "2021-09-08T13:56:19+00:00",
      "id": 1
    }
  ]
}

This endpoint retrieves post replies.

HTTP Request

GET http://dev.karab.in/api/post/{id}/comments

HTTP Request

Parameter	Type	Description
id	int	The ID of the post

Response

Field	Type	Nullable
@id	string	false
@type	string	false
magazine	object	false
user	object	false
parent	object	true
body	string	false
uv	int	false
createdAt	string	false
lastActive	string	false
id	int	false

Replies

Get Single Reply

curl "https://dev.karab.in/api/post_comments/{id}"

use Symfony\Contracts\HttpClient\HttpClientInterface;

$response = $this->client->request(
            'GET',
            'https://dev.karab.in/api/post_comments/{id}'
        );

$entries = $response->getContent();

import kbin from 'kbin-js-client';

let entries = kbin.replies.get({id});

{
  "@context": "/api/contexts/post_comment",
  "@id": "/api/post_comments/1",
  "@type": "post_comment",
  "magazine": {
    "@id": "/api/magazines/karabin",
    "@type": "magazine"
  },
  "user": {
    "@id": "/api/users/ernest",
    "@type": "user"
  },
  "parent": null,
  "body": "test",
  "uv": 0,
  "createdAt": "2021-09-08T13:56:19+00:00",
  "lastActive": "2021-09-08T13:56:19+00:00",
  "id": 1
}

This endpoint retrieves a specific reply.

HTTP Request

GET http://dev.karab.in/api/post_comments/{id}

HTTP Request

Parameter	Type	Description
id	int	The ID of the reply to retrieve

Response

Field	Type	Nullable
@id	string	false
@type	string	false
magazine	object	false
user	object	false
parent	object	true
body	string	false
uv	int	false
createdAt	string	false
lastActive	string	false
id	int	false

Errors

Kbin API uses the following error codes:

Error Code	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
405	Method Not Allowed
406	Not Acceptable
410	Gone
418	I'm a teapot.
429	Too Many Requests
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.