About This Documentation
Pixelnet’s API mixes both the Flarum API and the RSS feeds (the RSS feeds will not require a Flarum developer token)
This is the API for developing Pixelnet applications, API limits are subject to our anti-spam services.
Using the Pixelnet API
Pixelnet exposes a REST API used by its single-page application and available to external scripts. The API follows the JSON:API specification.
To extend the REST API with new endpoints, see Pixelnet developer documentation on API and data flow.
Authentication
The Pixelnet web application uses session cookies to authenticate with the API. External scripts can use stateless authentication with either API keys or access tokens.
GET endpoints can be used without authentication, but only content visible to guests will be returned. Other endpoints generally require authentication because of CSRF protection.
API Keys
API keys are the primary way for scripts, tools, and integrations to interact with Pixelnet.
Creating API Keys
Go to Security -> Developer Tokens -> Create New Developer Token
Fill these attributes:
key: A long, unique token. Recommended: 40-character alphanumeric string. This is the token used in the Authorization header.user\_id: Optional. If set, the key can only act as that user.
Other attributes are automatically filled or currently unused:
id: Filled by MySQL auto-increment.allowed\_ips: Not implemented.scopes: Not implemented.created\_at: Can be set to any date, but is intended to represent the key creation date.last\_activity\_at: Updated automatically when the token is used.
Using API Keys
Attach the key to each API request using the Authorization header. Include the user ID you want to act as at the end of the header:
Authorization: Token YOUR\_API\_KEY\_VALUE; userId=1
If user\_id is set for the key in the database, userId= is ignored. Otherwise, it can be set to any valid user ID in the database.
Access Tokens
Access tokens are short-lived tokens that belong to a specific user. They are used behind the scenes for cookie sessions. In stateless API requests, they behave like a regular session. The user’s last activity is updated whenever the token is used.
Creating Access Tokens
All users can create access tokens. Use the /api/token endpoint with the user’s credentials:
POST /api/token HTTP/1.1
{
"identification": "Toby",
"password": "pass7word"
}
Example response:
HTTP/1.1 200 OK
{
"token": "YACub2KLfe8mfmHPcUKtt6t2SMJOGPXnZbqhc3nX",
"userId": "1"
}
There are currently three token types, although only two can be created through the REST API:
session: Expires after 1 hour of inactivity. This is the default.session\_remember: Expires after 5 years of inactivity. Request this with remember=1.developer: Never expires. Currently, these can only be created manually in the database.
All access tokens are deleted when the user logs out, including developer tokens.
Using Access Tokens
Attach the returned token value to each API request with the Authorization header:
Authorization: Token YACub2KLfe8mfmHPcUKtt6t2SMJOGPXnZbqhc3nX
CSRF Protection
Most POST, PUT, and DELETE API endpoints are protected against cross-site request forgery. Stateless requests are not possible without authentication.
When using an API key or access token, CSRF protection is bypassed.
Endpoints
Flarum’s endpoint documentation is still in progress. Extensions can add endpoints and attributes, so a complete endpoint list depends on your installation.
A practical way to discover endpoints is to use your browser’s developer tools and inspect requests made by the Pixelnet web applicationlication.
List Discussions
GET /api/discussions
Example response:
{
"links": {
"first": "https://flarum.tld/api/discussions",
"next": "https://flarum.tld/api/discussions?page%5Boffset%5D=20"
},
"data": \[
{
"type": "discussions",
"id": "234",
"attributes": {
"title": "Lorem Ipsum",
"slug": "234-lorem-ipsum",
"commentCount": 10,
"participantCount": 3,
"createdAt": "2022-01-01T10:20:30+00:00",
"lastPostedAt": "2022-01-05T10:20:30+00:00",
"lastPostNumber": 10,
"canReply": true,
"canRename": true,
"canDelete": true,
"canHide": true,
"isHidden": true,
"hiddenAt": "2022-01-06T10:20:30+00:00",
"lastReadAt": "2022-01-02T10:20:30+00:00",
"lastReadPostNumber": 2,
"isApproved": true,
"canTag": true,
"isLocked": false,
"canLock": true,
"isSticky": false,
"canSticky": true,
"canMerge": true,
"subscription": null
},
"relationships": {
"user": {
"data": {
"type": "users",
"id": "1"
}
},
"lastPostedUser": {
"data": {
"type": "users",
"id": "64"
}
},
"tags": {
"data": \[
{
"type": "tags",
"id": "3"
}
]
},
"firstPost": {
"data": {
"type": "posts",
"id": "668"
}
}
}
}
],
"included": \[
{
"type": "users",
"id": "1",
"attributes": {
"username": "Admin",
"displayName": "Admin",
"avatarUrl": null,
"slug": "1"
}
},
{
"type": "tags",
"id": "3",
"attributes": {
"name": "Welcome",
"description": "Post interesting things here",
"slug": "welcome",
"color": "#888",
"discussionCount": 30,
"position": 1,
"isHidden": false,
"canStartDiscussion": true,
"canAddToDiscussion": true
}
}
]
}
Create Discussion
POST /api/discussions
Request body:
{
"data": {
"type": "discussions",
"attributes": {
"title": "Lorem Ipsum",
"content": "Hello World"
},
"relationships": {
"tags": {
"data": \[
{
"type": "tags",
"id": "1"
}
]
}
}
}
}
The response includes the ID of the new discussion:
{
"data": {
"type": "discussions",
"id": "42",
"attributes": {
"title": "Lorem Ipsum",
"slug": "42-lorem-ipsum",
"commentCount": 1
},
"relationships": {
"posts": {
"data": \[
{
"type": "posts",
"id": "58"
}
]
},
"user": {
"data": {
"type": "users",
"id": "1"
}
}
}
},
"included": \[
{
"type": "posts",
"id": "38",
"attributes": {
"number": 1,
"contentType": "comment",
"contentHtml": "<p>Hello World</p>"
}
}
]
}
Create User
POST /api/users
Request body:
{
"data": {
"attributes": {
"username": "Flarum",
"email": "user@example.com",
"password": "correcthorsebatterystaple"
}
}
}
Errors
Flarum uses HTTP status codes and error descriptions that follow the JSON:API error object format.
CSRF Token Mismatch
A 400 response with the csrf\_token\_mismatch code means the Authorization header is missing or invalid, and Flarum attempted to authenticate through the session cookie.
{
"errors": \[
{
"status": "400",
"code": "csrf\_token\_mismatch"
}
]
}
Validation Errors
Validation errors return HTTP status code 422. The invalid field is identified by the pointer value. Multiple errors can be returned for the same field.
{
"errors": \[
{
"status": "422",
"code": "validation\_error",
"detail": "The username has already been taken.",
"source": {
"pointer": "/data/attributes/username"
}
},
{
"status": "422",
"code": "validation\_error",
"detail": "The email has already been taken.",
"source": {
"pointer": "/data/attributes/email"
}
}
]
}