Shaarli API Documentation
Shaarli's REST API.
+This documentation is written according to API Blueprint specification.
+++Note: all requests reaching described services must include a valid JWT token in the HTTP header. See TODO for more informations.
+
Links ¶
Links
+Links Collection ¶
List All LinksGET/links{?offset,limit,searchterm,searchtags,private}
Retrieve a list of links ordered by creation date, eventually filtered with parameters.
+An empty array will be returned if no link is found with the filters provided.
+Example URI
- offset
number
(optional) Example: 40Offset from which to start listing links (default: 0)
+- limit
number
(optional) Example: 25Number of links to retrieve (default 20) or
+all
. +Note: usingall
can be very resource consuming with a big database, use it carefully.- searchterm
string
(optional) Example: shaarli+apiSearch terms across all links fields (url encoded string)
+- searchtags
string
(optional) Example: rest+httpSearch for specifics tags. Tag list should be separated by a
++
delimitor.- private
boolean
(required) Example: trueOnly fetch private links.
+
200
Body
[
+ {
+ "id": "20160606_101010",
+ "url": "http://foo.bar",
+ "title": "Link title",
+ "description": "Hello, world!",
+ "tags": [
+ "foo",
+ "bar"
+ ],
+ "private": false,
+ "created": "2015-05-05T12:30:00",
+ "updated": "``"
+ }
+]
Schema
{
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Link identifier"
+ },
+ "url": {
+ "type": "string",
+ "description": "Link URL"
+ },
+ "title": {
+ "type": "string",
+ "description": "Link title"
+ },
+ "description": {
+ "type": "string",
+ "description": "Link description"
+ },
+ "tags": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "List of tags associated with the link"
+ },
+ "private": {
+ "type": "boolean",
+ "description": "This flag is set to true when a link is private"
+ },
+ "created": {
+ "type": "string",
+ "description": "Creation datetime in ISO8601 format"
+ },
+ "updated": {
+ "type": "string",
+ "description": "NOT IMPLEMENTED YET. Link last update date."
+ }
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
400
Body
{
+ "code": 400,
+ "message": "Invalid parameters"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
401
Body
{
+ "code": 401,
+ "message": "Not authorized"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
Create a New LinkPOST/links
Create a new Link with provided request data.
+Note that the shaared URL must not exists. If none is provided, a note will be created (self linked shaare).
+Example URI
Headers
Content-Type: application/json
Body
{
+ "url": "http://foo.bar",
+ "title": "Link title",
+ "description": "Hello, world!",
+ "tags": [
+ "foo",
+ "bar"
+ ],
+ "private": false
+}
Schema
{
+ "$schema": "http://json-schema.org/draft-04/schema#",
+ "type": "object",
+ "properties": {
+ "url": {
+ "type": "string",
+ "description": "Link URL"
+ },
+ "title": {
+ "type": "string",
+ "description": "Link title"
+ },
+ "description": {
+ "type": "string",
+ "description": "Link description"
+ },
+ "tags": {
+ "type": "array",
+ "description": "List of tags associated with the link"
+ },
+ "private": {
+ "type": "boolean",
+ "description": "This flag is set to true when a link is private"
+ }
+ },
+ "required": [
+ "title"
+ ]
+}
201
The new link has been created, sending a redirection to the new link in Location
header.
Headers
Location: /links/1
Body
{
+ "id": "20160606_101010",
+ "url": "http://foo.bar",
+ "title": "Link title",
+ "description": "Hello, world!",
+ "tags": [
+ "foo",
+ "bar"
+ ],
+ "private": false,
+ "created": "2015-05-05T12:30:00",
+ "updated": "``"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Link identifier"
+ },
+ "url": {
+ "type": "string",
+ "description": "Link URL"
+ },
+ "title": {
+ "type": "string",
+ "description": "Link title"
+ },
+ "description": {
+ "type": "string",
+ "description": "Link description"
+ },
+ "tags": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "List of tags associated with the link"
+ },
+ "private": {
+ "type": "boolean",
+ "description": "This flag is set to true when a link is private"
+ },
+ "created": {
+ "type": "string",
+ "description": "Creation datetime in ISO8601 format"
+ },
+ "updated": {
+ "type": "string",
+ "description": "NOT IMPLEMENTED YET. Link last update date."
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
400
Body
{
+ "code": 400,
+ "message": "Invalid parameters"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
401
Body
{
+ "code": 401,
+ "message": "Not authorized"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
409
Conflict: another link with the same URL has been found. The existing link is returned in the body of the response.
+Body
{
+ "id": "20160606_101010",
+ "url": "http://foo.bar",
+ "title": "Link title",
+ "description": "Hello, world!",
+ "tags": [
+ "foo",
+ "bar"
+ ],
+ "private": false,
+ "created": "2015-05-05T12:30:00",
+ "updated": "``"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Link identifier"
+ },
+ "url": {
+ "type": "string",
+ "description": "Link URL"
+ },
+ "title": {
+ "type": "string",
+ "description": "Link title"
+ },
+ "description": {
+ "type": "string",
+ "description": "Link description"
+ },
+ "tags": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "List of tags associated with the link"
+ },
+ "private": {
+ "type": "boolean",
+ "description": "This flag is set to true when a link is private"
+ },
+ "created": {
+ "type": "string",
+ "description": "Creation datetime in ISO8601 format"
+ },
+ "updated": {
+ "type": "string",
+ "description": "NOT IMPLEMENTED YET. Link last update date."
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
Link ¶
View Link detailsGET/links/{linkID}
Example URI
- linkID
string
(required) Example: 20160606_101010Link identifier
+
200
Body
{
+ "id": "20160606_101010",
+ "url": "http://foo.bar",
+ "title": "Link title",
+ "description": "Hello, world!",
+ "tags": [
+ "foo",
+ "bar"
+ ],
+ "private": false,
+ "created": "2015-05-05T12:30:00",
+ "updated": "``"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Link identifier"
+ },
+ "url": {
+ "type": "string",
+ "description": "Link URL"
+ },
+ "title": {
+ "type": "string",
+ "description": "Link title"
+ },
+ "description": {
+ "type": "string",
+ "description": "Link description"
+ },
+ "tags": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "List of tags associated with the link"
+ },
+ "private": {
+ "type": "boolean",
+ "description": "This flag is set to true when a link is private"
+ },
+ "created": {
+ "type": "string",
+ "description": "Creation datetime in ISO8601 format"
+ },
+ "updated": {
+ "type": "string",
+ "description": "NOT IMPLEMENTED YET. Link last update date."
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
401
Body
{
+ "code": 401,
+ "message": "Not authorized"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
404
Body
{
+ "code": 404,
+ "message": "Not found"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
Update a linkPUT/links/{linkID}
Update an existing link with provided request data. Keep in mind that all link’s fields will be updated.
+Example URI
- linkID
string
(required) Example: 20160606_101010Link identifier
+
Headers
Content-Type: application/json
Body
{
+ "url": "http://foo.bar",
+ "title": "Link title",
+ "description": "Hello, world!",
+ "tags": [
+ "foo",
+ "bar"
+ ],
+ "private": false
+}
Schema
{
+ "$schema": "http://json-schema.org/draft-04/schema#",
+ "type": "object",
+ "properties": {
+ "url": {
+ "type": "string",
+ "description": "Link URL"
+ },
+ "title": {
+ "type": "string",
+ "description": "Link title"
+ },
+ "description": {
+ "type": "string",
+ "description": "Link description"
+ },
+ "tags": {
+ "type": "array",
+ "description": "List of tags associated with the link"
+ },
+ "private": {
+ "type": "boolean",
+ "description": "This flag is set to true when a link is private"
+ }
+ },
+ "required": [
+ "title"
+ ]
+}
200
The existing link has been updated.
+Body
{
+ "id": "20160606_101010",
+ "url": "http://foo.bar",
+ "title": "Link title",
+ "description": "Hello, world!",
+ "tags": [
+ "foo",
+ "bar"
+ ],
+ "private": false,
+ "created": "2015-05-05T12:30:00",
+ "updated": "``"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Link identifier"
+ },
+ "url": {
+ "type": "string",
+ "description": "Link URL"
+ },
+ "title": {
+ "type": "string",
+ "description": "Link title"
+ },
+ "description": {
+ "type": "string",
+ "description": "Link description"
+ },
+ "tags": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "List of tags associated with the link"
+ },
+ "private": {
+ "type": "boolean",
+ "description": "This flag is set to true when a link is private"
+ },
+ "created": {
+ "type": "string",
+ "description": "Creation datetime in ISO8601 format"
+ },
+ "updated": {
+ "type": "string",
+ "description": "NOT IMPLEMENTED YET. Link last update date."
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
400
Body
{
+ "code": 400,
+ "message": "Invalid parameters"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
401
Body
{
+ "code": 401,
+ "message": "Not authorized"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
404
Body
{
+ "code": 404,
+ "message": "Not found"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
409
Conflict. Given URL already exists for another link, which is returned in the response body.
+Body
{
+ "id": "20160606_101010",
+ "url": "http://foo.bar",
+ "title": "Link title",
+ "description": "Hello, world!",
+ "tags": [
+ "foo",
+ "bar"
+ ],
+ "private": false,
+ "created": "2015-05-05T12:30:00",
+ "updated": "``"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Link identifier"
+ },
+ "url": {
+ "type": "string",
+ "description": "Link URL"
+ },
+ "title": {
+ "type": "string",
+ "description": "Link title"
+ },
+ "description": {
+ "type": "string",
+ "description": "Link description"
+ },
+ "tags": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "List of tags associated with the link"
+ },
+ "private": {
+ "type": "boolean",
+ "description": "This flag is set to true when a link is private"
+ },
+ "created": {
+ "type": "string",
+ "description": "Creation datetime in ISO8601 format"
+ },
+ "updated": {
+ "type": "string",
+ "description": "NOT IMPLEMENTED YET. Link last update date."
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
History ¶
Get last user actionsGET/history{?since,offset,limit}
Retrieve the last actions made by the user, even in the web version, including:
+-
+
-
+
+CREATED
: A new link has been created.
+ -
+
+UPDATED
: An existing link has been updated.
+ -
+
+DELETED
: A link has been deleted.
+ -
+
+SETTINGS
: Shaarli settings have been updated.
+
++This service can be useful to maintain a local database.
+
Example URI
- since
string
(optional) Example: 2015-05-05T12:30:00Get all event since this datetime (format ISO ISO8601).
+- offset
number
(optional) Example: 40Offset from which to start listing links (default: 0). Incompatible with
+since
parameter.- limit
number
(optional) Example: 25Number of links to retrieve (default 20) or
+all
. Incompatible withsince
parameter.
200
Body
[
+ {
+ "event": "CREATED",
+ "datetime": "2015-05-05T12:30:00",
+ "id": "20160606_101010"
+ }
+]
Schema
{
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "event": {
+ "type": "string",
+ "description": "An event code matching a user action."
+ },
+ "datetime": {
+ "type": "string",
+ "description": "Event datetime in ISO8601 format"
+ },
+ "id": {
+ "type": "string",
+ "description": "Identifier of the logged event (e.g.: created link ID)."
+ }
+ },
+ "required": [
+ "event",
+ "datetime"
+ ]
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
400
Body
{
+ "code": 400,
+ "message": "Invalid parameters"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
401
Body
{
+ "code": 401,
+ "message": "Not authorized"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
Instance information ¶
Get instance infoGET/infos
Return a list of information and settings for the Shaarli instance.
+Example URI
401
Body
{
+ "code": 401,
+ "message": "Not authorized"
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}
200
Body
{
+ "global_counter": 654,
+ "private_counter": 123,
+ "settings": {
+ "title": "My links",
+ "header_link": "https://foo.bar/shaarli",
+ "timezone": "Europe/Paris",
+ "enabled_plugins": [
+ "qrcode",
+ "markdown"
+ ],
+ "default_private_links": true
+ }
+}
Schema
{
+ "type": "object",
+ "properties": {
+ "global_counter": {
+ "type": "number",
+ "description": "Number of links stored in this Shaarli instance (private and public)"
+ },
+ "private_counter": {
+ "type": "number",
+ "description": "Number of private links stored"
+ },
+ "settings": {
+ "type": "object",
+ "properties": {
+ "title": {
+ "type": "string",
+ "description": "Shaarli's instance title."
+ },
+ "header_link": {
+ "type": "string",
+ "description": "Link to the homepage."
+ },
+ "timezone": {
+ "type": "string",
+ "description": "Shaarli's instance timezone."
+ },
+ "enabled_plugins": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "List of enabled plugins."
+ },
+ "default_private_links": {
+ "type": "boolean",
+ "description": "Check the private checkbox by default for every new link."
+ }
+ }
+ }
+ },
+ "required": [
+ "global_counter",
+ "private_counter"
+ ],
+ "$schema": "http://json-schema.org/draft-04/schema#"
+}