Skip to main content

REST API

Authentication​

All HTTP requests by the API must be authenticated with an API token.

You can generate at most 10 API tokens on Settings page.

The API token is used in the header Authorization of a HTTP request:

Authorization: Token <Token>

or

Authorization: Bearer <Token>

For example, get your profile by the following API (Replace the following token with yours):

$ curl -H 'Authorization: Token 97e235803f90f5db6352b694cc1ce895a7d55433bddf3dad0ef8f097eebf3cab' https://metaessen.com/api/user/me/

API​

Resource​

Create a resource​

POST /api/esn/

Request body parameters:

  • url

    The URL or identity of the resource.

    It should be blank when internal_url is true.

    Type: String

    Example: https://metaessen.com/

  • internal_url

    Whether to create the internal URL for the resource automatically.

    Type: Boolean

    Example: false

  • name

    The name or title of the resource.

    Type: String

    Example: Metaessen - Manage resources for practical use

  • introduction

    The brief description of the resource.

    Type: String

    Example: Manage resources by simulating the real world, focus on what you matter, not be distracted by the unnecessary, grasp the essence and big picture faster and better.

  • keywords

    A list of keyword to describe the resource.

    Type: List (["keyword_content", ...])

    Example: ["Bookmark manager"]

  • format

    The format of resource introduction.

    Type: Enumeration (one of the following values)

    • null

      Default format (you can set it on Settings page)

    • 1

      Plain text

    • 2

      Markdown

    Example: 2

Response format:

  • system

    The system ID which is bound with the resource.

    Type: UUID or null

    Example: 69cfa55a-24ef-4cba-9789-32b5844b36bc

  • instance_count

    The number of resource instances of the resource.

    Type: Number

    Example: 0

{
    "id": "ab61aea0-a359-4f50-a862-99e99bbe81d6",
    "url": "https://metaessen.com/essence/",
    "name": "resource name",
    "introduction": "resource introduction",
    "keywords": [
        {
            "id": "ddf6ca0c-ed2d-446c-92e0-ccf8ba1a8cfd",
            "content": "Keyword 1",
            "bound_time": "2026-08-18T07:30:55.783903Z"
        }
    ],
    "format": null,
    "system": null,
    "instance_count": 0,
    "created_time": "2026-08-18T07:30:55.777900Z",
    "updated_time": "2026-08-18T07:30:55.778184Z"
}

Retrieve a resource​

GET /api/esn/<id>/

Retrieve a single resource by ID.

Request URL parameters:

  • id

    The resource ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Response format:

{
    "id": "cb26c852-88d5-4175-81b9-69f19f80432e",
    "url": "https://metaessen.com/esn/cb26c852-88d5-4175-81b9-69f19f80432e/",
    "name": "resource name",
    "introduction": "resource introduction",
    "keywords": [
        {
            "id": "ddf6ca0c-ed2d-446c-92e0-ccf8ba1a8cfd",
            "content": "Keyword 1",
            "bound_time": "2026-08-18T08:10:58.488415Z"
        }
    ],
    "format": 1,
    "system": null,
    "instance_count": 0,
    "created_time": "2026-08-18T08:10:58.480409Z",
    "updated_time": "2026-08-18T08:10:58.480705Z"
}

Update a resource​

PUT /api/esn/<id>/
PATCH /api/esn/<id>/

Update a resource by ID.

The method PUT requires that all required fields must be provied, but PATCH has no the requirement and just update the provided fields.

url field is required now.

If any field is not provided, its value will not be changed.

Request URL parameters:

  • id

    The resource ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Request body parameters (refer to Create a resource).

Example of request body

{"url":"https://metaessen.com/esn/cb26c852-88d5-4175-81b9-69f19f80432e/","name":"resource name","introduction":"resource introduction","keywords":[],"format":1}

Response format:

{
    "id": "cb26c852-88d5-4175-81b9-69f19f80432e",
    "url": "https://metaessen.com/esn/cb26c852-88d5-4175-81b9-69f19f80432e/",
    "name": "resource name",
    "introduction": "resource introduction",
    "keywords": [],
    "format": 1,
    "system": null,
    "instance_count": 0,
    "created_time": "2026-08-18T08:10:58.480409Z",
    "updated_time": "2026-08-18T09:05:25.296892Z"
}

Delete a resource​

DELETE /api/esn/<id>/

Delete a resource by ID.

Request URL parameters:

  • id

    The resource ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Successful response status code: 204

List resources​

GET /api/esn/

Get a list of resources.

Request URL query parameters:

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      -createdtime, -name, -updatedtime, -url, createdtime, name, updatedtime, url

    • Default value: -createdtime

    Example: -name

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/esn/?ordering=-createdtime&page=1

Response format:

{
    "count": 4713,
    "next": "https://metaessen.com/api/esn/?ordering=-createdtime&page=2",
    "previous": null,
    "results": [
        {
            "id": "cb26c852-88d5-4175-81b9-69f19f80432e",
            "url": "https://metaessen.com/esn/cb26c852-88d5-4175-81b9-69f19f80432e/",
            "name": "resource name",
            "introduction": "resource introduction",
            "keywords": [],
            "format": 1,
            "system": null,
            "instance_count": 0,
            "created_time": "2026-08-18T08:10:58.480409Z",
            "updated_time": "2026-08-18T09:05:25.296892Z"
        },

        ...
    ]
}

List instances of a resource​

GET /api/esn/<id>/instances/

Get all resource instances of a resource.

  • id

    The resource ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Response format:

  • user_esn

    The data of the resource of the resource instance.

    Type: Dictionary or Object

[
    {
        "id": "7f58ef9e-dc5d-4def-a165-98aba06b1343",
        "system": "ee80e7c7-d475-4e4c-bc4c-6ddbecbf0cbf",
        "user_esn": "90e05c27-7d4a-4800-917d-5dedfbb6ad32",
        "name": "Hypertext Transfer Protocol - Wikipedia, the free encyclopedia",
        "introduction": null,
        "keywords": [],
        "order": 2,
        "format": null,
        "created_time": "2024-05-31T07:36:40Z",
        "updated_time": "2025-07-21T09:05:09.636882Z"
    }
]

Search resources​

POST /api/esn/search/

Search resources by some string.

Request URL query parameters:

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/esn/search/?page=1

Request body parameters:

  • search_string

    Type: String

    Example: cache

  • options

    Type: Dictionary or Object

    • case_sensitive

      Whether to think about the uppercase or lowercase of the search string.

      Type: Boolean

    • include_id

      Whether to search the resource ID.

      Type: Boolean

    • include_name

      Whether to search the resource name.

      Type: Boolean

    • include_introduction

      Whether to search the resource introduction.

      Type: Boolean

    • include_keywords

      Whether to search the resource keywords.

      Type: Boolean

    • include_url

      Whether to search the resource url.

      Type: Boolean

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      -createdtime, -name, -updatedtime, -url, createdtime, name, updatedtime, url

    • Default value: -createdtime

    Example: -name

Example of request body:

{"search_string":"cache","options":{"case_sensitive":false,"include_id":true,"include_name":true,"include_introduction":true,"include_keywords":true,"include_url":true},"ordering":"-createdtime"}

Response format:

{
    "count": 4,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "1b892a23-c1ef-4a05-89c7-a4054fbb9155",
            "url": "https://tools.ietf.org/html/rfc7230",
            "name": "RFC 7230 - Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing",
            "introduction": null,
            "keywords": [],
            "format": 1,
            "system": null,
            "instance_count": 1,
            "created_time": "2024-08-11T15:40:10Z",
            "updated_time": "2025-07-21T09:04:34.248959Z"
        },

        ...
    ]
}

Filter resources​

POST /api/esn/keywords_filter/

Filter resources by keywords.

Request URL query parameters:

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/esn/keywords_filter/?page=1

Request body parameters:

  • keywords

    A list of keyword to describe the resource.

    Type: List (["keyword_content", ...])

    Example: ["Bookmark manager"]

  • include_all

    Whether to include all keywords or just include any of keywords for filtered resources.

    Type: Boolean

    Example: true

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      -createdtime, -name, -updatedtime, -url, createdtime, name, updatedtime, url

    • Default value: -createdtime

    Example: -name

Example of request body:

{"keywords":["abc"],"include_all":true,"ordering":"-createdtime"}

Response format:

{
    "count": 8,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "0fd91dda-03a8-44fa-a591-c709ce0983b2",
            "url": "https://tailwindcss.com/docs/text-decoration-color",
            "name": "text-decoration-color - Typography - Tailwind CSS",
            "introduction": "Utilities for controlling the color of text decorations.",
            "keywords": [
                {
                    "id": "b7d9f9f7-8e94-44ee-bb7c-b8c24ba7a019",
                    "content": "tailwind",
                    "bound_time": "2026-06-26T06:22:06.834223Z"
                }
            ],
            "format": null,
            "system": null,
            "instance_count": 3,
            "created_time": "2026-06-26T06:22:06.824630Z",
            "updated_time": "2026-06-26T06:22:06.825001Z"
        },
        ...
    ]
}

Edit a group of resources​

POST /api/esn/edit_resources/

Add keywords, delete keywords, clear all keywords, or change text format for a group of resources.

Request body parameters:

  • ids

    A list of resource IDs to edit.

    Type: List

    Example: ["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"]

  • exclude_ids

    A list of resource IDs to exclude for editing.

    Type: List

    Example: ["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"]

  • is_all

    Whether to edit all resources.

    warning

    If is_all is true, the service will edit all of your resources except the ones in exclude_ids.

    Type: Boolean

    Example: false

  • words_to_update_all

    If is_all is true and avoiding the wrong operations, the words_to_update_all should be the exact string: UPDATE ALL RESOURCES FOR <username> (Replace <username> by your username).

    Type: String

    Example: UPDATE ALL RESOURCES FOR auser

  • keywords_to_add

    A list of keywords to add.

    Type: List

    Example: ["keyword 1"]

  • keywords_to_delete

    A list of keywords to delete.

    Type: List

    Example: ["keyword 2"]

  • is_clear_keywords

    Whether to clear all keywords.

    warning

    If is_clear_keywords is true, the service will clear all keywords of selected resources.

    Type: Boolean

    Example: false

  • format

    The format of resource introduction to change.

    Type: Enumeration (one of the following values)

    • null

      Default format (you can set it on Settings page)

    • 1

      Plain text

    • 2

      Markdown

    Example: 2

  • search_params

    If wantting to edit or delete all resources by searching, you can use this parameter.

    is_all should be true in this situation.

    Refer to Search resources for the specific parameters.

    Type: Object or Dictionary

  • keyword_filter_params

    If wantting to edit or delete all resources by keyword filter, you can use this parameter.

    is_all should be true in this situation.

    Refer to Filter resources for the specific parameters.

    Type: Object or Dictionary

Example of request body:

{"ids":["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"],"is_all":false,"exclude_ids":[],"keywords_to_add":["keyword 1"],"keywords_to_delete":[],"is_clear_keywords":false,"format":0}

Successful response status code: 200

Delete a group of resources​

POST /api/esn/delete_resources/

Delete a group of resources permanently.

danger

This action will delete the selected resources, and all resource instances of them.

Request body parameters:

  • ids

    A list of resource IDs to delete.

    Type: List

    Example: ["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"]

  • exclude_ids

    A list of resource IDs to exclude for deleting.

    Type: List

    Example: ["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"]

  • is_all

    Whether to delete all resources.

    danger

    If is_all is true, the service will delete all of your resources except the ones in exclude_ids.

    Type: Boolean

    Example: false

  • words_to_delete_all

    If is_all is true and avoiding the wrong operations, the words_to_update_all should be the exact string: DELETE ALL RESOURCES FOR <username> (Replace <username> by your username).

    Type: String

    Example: DELETE ALL RESOURCES FOR auser

  • search_params

    If wantting to edit or delete all resources by searching, you can use this parameter.

    is_all should be true in this situation.

    Refer to Search resources for the specific parameters.

    Type: Object or Dictionary

  • keyword_filter_params

    If wantting to edit or delete all resources by keyword filter, you can use this parameter.

    is_all should be true in this situation.

    Refer to Filter resources for the specific parameters.

    Type: Object or Dictionary

Example of request body:

{"ids":["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"],"is_all":false,"exclude_ids":[]}

Response format:

{"deleted_instances_number":1,"deleted_resources_number":2}

Get a resource by URL​

POST /api/esn/resource_by_url/

Get the resource data by a URL.

Request body parameters:

  • url

    The URL or identity of the resource to get.

    Type: String

    Example: https://metaessen.com/

Response format:

{
    "id": "ab61aea0-a359-4f50-a862-99e99bbe81d6",
    "url": "https://metaessen.com/essence/",
    "name": "resource name",
    "introduction": "resource introduction",
    "keywords": [
        {
            "id": "ddf6ca0c-ed2d-446c-92e0-ccf8ba1a8cfd",
            "content": "Keyword 1",
            "bound_time": "2026-08-18T07:30:55.783903Z"
        }
    ],
    "format": null,
    "system": null,
    "instance_count": 0,
    "created_time": "2026-08-18T07:30:55.777900Z",
    "updated_time": "2026-08-18T07:30:55.778184Z"
}

Resource instance​

Create a resource instance​

POST /api/iesn/

Request body parameters:

  • system

    The system to which the resource instance belongs (the parent system of the resource instance).

    Type: UUID (the string of the ID of a system)

    Example: c72b05b4-3949-4b1f-a583-15ce1f99185b

  • url

    The URL or identity of the resource to which the resource instance belongs.

    It should be blank when internal_url is true.

    Type: String

    Example: https://metaessen.com/

  • internal_url

    Whether to create the internal URL for the resource of the resource instance.

    Type: Boolean

    Example: false

  • name

    The name or title of the resource instance.

    Type: String

    Example: Metaessen - Manage resources for practical use

  • introduction

    The brief description of the resource instance.

    Type: String

    Example: Manage resources by simulating the real world, focus on what you matter, not be distracted by the unnecessary, grasp the essence and big picture faster and better.

  • keywords

    A list of keyword to describe the resource instance.

    Type: List (["keyword_content", ...])

    Example: ["Bookmark manager"]

  • order

    The system order of the resource instance in the parent system.

    Type: Number or null

    • Number

      This is the exact order. If it is beyond zero or the max number of children in the parent system, the order will be the zero or the number of last item respectively.

    • null

      The field can be null and it means the resource instance will be put into the last position.

    Example: 0

  • format

    The format of resource instance introduction.

    Type: Enumeration (one of the following values)

    • null

      Default format (you can set it on Settings page)

    • 1

      Plain text

    • 2

      Markdown

    Example: 2

  • for_what

    Type: Enumeration (one of the following values)

    • esn_and_iesn

      Create the resource instance and the corresponding resource at the same time using the same data.

    • iesn

      Only create the resource instance using the full data and don't create the descriptive fields for the corresponding resource.

    • esn

      Only create the corresponding resource using the full data and don't create the descriptive field for the resource instance.

    Example: esn_and_iesn

Example of request body:

{"system":"c72b05b4-3949-4b1f-a583-15ce1f99185b","url":"https://docs.python.org/3/library/os.html","name":"os — Miscellaneous operating system interfaces — Python 3.14.7 documentation","introduction":"","keywords":["Python library os"],"order":null,"format":2,"for_what":"esn_and_iesn","internal_url":false}

Response format:

  • system

    The parent system ID of the created resource instance.

  • user_esn

    The resource of the created resource instance.

  • esn_created

    Whether the resource is created when creating the resource instance.

{
    "id": "b8377371-c7f6-495b-9f1e-0b5d2adbc37a",
    "system": "c72b05b4-3949-4b1f-a583-15ce1f99185b",
    "user_esn": {
        "id": "6167302a-d262-4755-96f4-ec723dc28411",
        "url": "https://docs.python.org/3/library/os.html#files-and-directories",
        "name": "os — Miscellaneous operating system interfaces — Python 3.14.7 documentation",
        "introduction": "",
        "keywords": [
            {
                "id": "e4af9433-fb63-4d45-ad3c-02bee110b160",
                "content": "Python library os",
                "bound_time": "2026-08-21T10:01:21.179043Z"
            }
        ],
        "format": 2,
        "system": null,
        "instance_count": 1,
        "created_time": "2026-08-21T10:01:21.166198Z",
        "updated_time": "2026-08-21T10:01:21.166658Z"
    },
    "name": "os — Miscellaneous operating system interfaces — Python 3.14.7 documentation",
    "introduction": "",
    "keywords": [
        {
            "id": "e4af9433-fb63-4d45-ad3c-02bee110b160",
            "content": "Python library os",
            "bound_time": "2026-08-21T10:01:21.211461Z"
        }
    ],
    "order": 3,
    "format": 2,
    "created_time": "2026-08-21T10:01:21.200373Z",
    "updated_time": "2026-08-21T10:01:21.200934Z",
    "esn_created": true
}

Retrieve a resource instance​

GET /api/iesn/<id>/

Retrieve a single resource instance by ID.

Request URL parameters:

  • id

    The resource instance ID.

    Type: UUID

    Example: b8377371-c7f6-495b-9f1e-0b5d2adbc37a

Response format:

{
    "id": "b8377371-c7f6-495b-9f1e-0b5d2adbc37a",
    "system": "c72b05b4-3949-4b1f-a583-15ce1f99185b",
    "user_esn": {
        "id": "6167302a-d262-4755-96f4-ec723dc28411",
        "url": "https://docs.python.org/3/library/os.html#files-and-directories",
        "name": "os — Miscellaneous operating system interfaces — Python 3.14.7 documentation",
        "introduction": "",
        "keywords": [
            {
                "id": "e4af9433-fb63-4d45-ad3c-02bee110b160",
                "content": "Python library os",
                "bound_time": "2026-08-21T10:01:21.179043Z"
            }
        ],
        "format": 2,
        "system": null,
        "instance_count": 1,
        "created_time": "2026-08-21T10:01:21.166198Z",
        "updated_time": "2026-08-21T10:01:21.166658Z"
    },
    "name": "os — Miscellaneous operating system interfaces — Python 3.14.7 documentation",
    "introduction": "",
    "keywords": [
        {
            "id": "e4af9433-fb63-4d45-ad3c-02bee110b160",
            "content": "Python library os",
            "bound_time": "2026-08-21T10:01:21.211461Z"
        }
    ],
    "order": 3,
    "format": 2,
    "created_time": "2026-08-21T10:01:21.200373Z",
    "updated_time": "2026-08-21T10:01:21.200934Z",
}

Update a resource instance​

PUT /api/iesn/<id>/
PATCH /api/iesn/<id>/

Update a resource instance by ID.

The method PUT requires that all required fields must be provied, but PATCH has no the requirement and just update the provided fields.

url and system fields are required now.

If any field is not provided, its value will not be changed.

Request URL parameters:

  • id

    The resource instance ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Request body parameters (refer to Create a resource instance).

  • name

  • introduction

  • keywords

  • order

  • format

  • is_update_resource

    Type: Enumeration (one of the following values)

    • no

      Don't update the corresponding resource.

    • with_resource_having_only_instance

      Update the corresponding resource if it having only instance.

      This is the default value.

    • with_resource

      Update the corresponding resource anyway.

    Example: with_resource_having_only_instance

Example of request body

{"name":"os — Miscellaneous operating system interfaces — Python 3.14.7 documentation","introduction":"","keywords":["Python"],"order":3,"format":2,"is_update_resource":"with_resource_having_only_instance"}

Response format:

{
    "id": "b8377371-c7f6-495b-9f1e-0b5d2adbc37a",
    "system": "c72b05b4-3949-4b1f-a583-15ce1f99185b",
    "user_esn": {
        "id": "6167302a-d262-4755-96f4-ec723dc28411",
        "url": "https://docs.python.org/3/library/os.html",
        "name": "os — Miscellaneous operating system interfaces — Python 3.14.7 documentation",
        "introduction": "",
        "keywords": [
            {
                "id": "6e3b6d9d-282b-4b5a-a576-5931b48a8920",
                "content": "Python",
                "bound_time": "2026-08-21T10:36:55.125330Z"
            }
        ],
        "format": 2,
        "system": null,
        "instance_count": 1,
        "created_time": "2026-08-21T10:01:21.166198Z",
        "updated_time": "2026-08-21T10:36:55.102395Z"
    },
    "name": "os — Miscellaneous operating system interfaces — Python 3.14.7 documentation",
    "introduction": "",
    "keywords": [
        {
            "id": "6e3b6d9d-282b-4b5a-a576-5931b48a8920",
            "content": "Python",
            "bound_time": "2026-08-21T10:36:55.083953Z"
        }
    ],
    "order": 3,
    "format": 2,
    "created_time": "2026-08-21T10:01:21.200373Z",
    "updated_time": "2026-08-21T10:36:55.061696Z"
}

Delete a resource instance​

DELETE /api/iesn/<id>/
POST /api/iesn/<id>/delete/

Delete a resource instance by ID.

note

The API DELETE /api/iesn/<id> just deletes the resource instance and has no the following option.

The API POST /api/iesn/<id>/delete/ has the following option.

You should use /api/iesn/delete_instances/ or /api/iesn/<id>/delete/ to delete a resource instance.

tip

You can also use the api /api/iesn/delete_instances/ to delete a specific resource instance. The api will return the number of deleted resources or resource instances.

It's better to use the api to delete a resource instance.

Request URL parameters:

  • id

    The resource instance ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Request body parameters:

  • option

    Type: Enumeration (one of the following values)

    • instance

      Delete the resource instance only.

    • with_resource

      Also delete the corresponding resource anyway (Will delete other instances of the resource).

    • with_resource_having_only_instance

      Also delete the corresponding resource if having only instance.

      This is the default value.

    Example: with_resource_having_only_instance

Successful response status code: 204

List resource instances​

GET /api/iesn/

Get a list of resource instances.

Request URL query parameters:

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      -createdtime, -name, -updatedtime, -url, createdtime, name, updatedtime, url

    • Default value: -createdtime

    Example: -name

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/iesn/?ordering=-createdtime&page=1

Response format:

{
    "count": 4713,
    "next": "https://metaessen.com/api/iesn/?ordering=-createdtime&page=2",
    "previous": null,
    "results": [
        {
            "id": "fa33ed4b-13ec-43ef-bd22-01f491ccdfc1",
            "system": "f804b2c1-4ec2-4149-8c97-40fe5a2794f1",
            "user_esn": {
                "id": "4c3dc451-3239-41e7-87c1-7c4b17c4ebc5",
                "url": "http://www.tldp.org/",
                "name": "The Linux Documentation Project",
                "introduction": null,
                "keywords": [],
                "format": 1,
                "system": null,
                "instance_count": 1,
                "created_time": "2024-08-11T15:40:11Z",
                "updated_time": "2025-07-21T09:04:38.205080Z"
            },
            "name": "The Linux Documentation Project",
            "introduction": null,
            "keywords": [],
            "order": 32,
            "format": null,
            "created_time": "2024-05-31T07:36:40Z",
            "updated_time": "2025-07-21T09:05:23.362170Z"
        },
        ...
    ]
}

Search resource instances​

POST /api/iesn/search/

Search resource instances by some string.

Request URL query parameters:

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/iesn/search/?page=1

Request body parameters:

  • search_string

    Type: String

    Example: markdown

  • system_tree

    Which system tree to search for resource instances.

    Type: UUID or String

    • none

      It means the ROOT system.

      Default value.

    • UUID

      A specific system which is the root of the sub system tree.

    Example: 69cfa55a-24ef-4cba-9789-32b5844b36bc

  • where

    The specific place in the system tree.

    Type: Enumeration (one of the following values)

    • root

      Just search the resource instances belonging to the root system.

    • descendants

      Search all resource instances belonging to descendant systems.

    • root_and_descendants

      Search all resource instances belonging to the root and descendant systems.

      Default value.

    • children

      Just search the resouce instances belonging to the child systems of the root system.

    Example: root_and_descendants

  • options

    Type: Dictionary or Object

    • case_sensitive

      Whether to think about the uppercase or lowercase of the search string.

      Type: Boolean

    • include_id

      Whether to search the resource and resource instance ID.

      Type: Boolean

    • include_name

      Whether to search the resource and resource instance name.

      Type: Boolean

    • include_introduction

      Whether to search the resource and resource instance introduction.

      Type: Boolean

    • include_keywords

      Whether to search the resource and resource instance keywords.

      Type: Boolean

    • include_url

      Whether to search the resource url.

      Type: Boolean

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      -createdtime, -name, -updatedtime, -url, -path, createdtime, name, updatedtime, url, path

      • path

        The system path of a resource instance.

        Example: /Bookmarks

    • Default value: -createdtime

    Example: -name

Example of request body:

{"search_string":"markdown","system_tree":"none","where":"root_and_descendants","options":{"case_sensitive":false,"include_id":true,"include_name":true,"include_introduction":true,"include_keywords":true,"include_url":true},"ordering":"-createdtime"}

Response format:

{
    "count": 215,
    "next": "https://metaessen.com/api/iesn/search/?page=2",
    "previous": null,
    "results": [
        {
            "id": "95ecdc85-bafa-4eb2-837a-a61ba20cae7c",
            "system": "eb5aaa26-d8fb-4af9-9990-9173462be385",
            "user_esn": {
                "id": "f6c6e36d-e2ce-4a96-95af-6422112468a1",
                "url": "https://python-markdown.github.io/#1",
                "name": "Python-Markdown — Python-Markdown 3.8.2 documentation",
                "introduction": "",
                "keywords": [],
                "format": null,
                "system": null,
                "instance_count": 1,
                "created_time": "2026-07-07T15:35:10.825005Z",
                "updated_time": "2026-07-07T15:35:10.825569Z"
            },
            "name": "Python-Markdown — Python-Markdown 3.8.2 documentation",
            "introduction": "",
            "keywords": [],
            "order": 0,
            "format": null,
            "created_time": "2026-07-07T15:35:10.849576Z",
            "updated_time": "2026-07-07T15:35:10.849970Z"
        },
        ...
    ]
}

Filter resource instances​

POST /api/iesn/keywords_filter/

Filter resource instances by keywords.

Request URL query parameters:

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/iesn/keywords_filter/?page=1

Request body parameters:

  • keywords

    A list of keyword to describe the resource.

    Type: List (["keyword_content", ...])

    Example: ["Bookmark manager"]

  • include_all

    Whether to include all keywords or just include any of keywords for filtered resource instances.

    Type: Boolean

    Example: true

  • system_tree

    Refer to Search resource instances

  • where

    Refer to Search resource instances

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      -createdtime, -name, -updatedtime, -url, -path, createdtime, name, updatedtime, url, path

    • Default value: -createdtime

    Example: -name

Example of request body:

{"keywords":["django"],"include_all":true,"system_tree":"none","where":"root_and_descendants","ordering":"-createdtime"}

Response format:

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "9a370d66-e62a-4fb8-832a-df85df7c00e6",
            "system": "58a04de8-7731-432a-ae82-028a05fdc903",
            "user_esn": {
                "id": "398d3fa1-2ee8-406a-8d0d-031ea2266fa0",
                "url": "https://www.djangoproject.com/",
                "name": "The Web framework for perfectionists with deadlines | Django",
                "introduction": "The web framework for perfectionists with deadlines.",
                "keywords": [],
                "format": 1,
                "system": "121eee44-f4be-4c7b-979f-0b86f03799c5",
                "instance_count": 3,
                "created_time": "2024-08-11T15:40:10Z",
                "updated_time": "2025-07-21T09:03:56.914801Z"
            },
            "name": "The web framework for perfectionists with deadlines | Django",
            "introduction": "The web framework for perfectionists with deadlines.",
            "keywords": [
                {
                    "id": "f9ddde40-6719-4454-8f3f-aad1203aa54d",
                    "content": "Django",
                    "bound_time": "2025-07-21T09:07:46.118597Z"
                }
            ],
            "order": 9,
            "format": null,
            "created_time": "2024-11-29T02:27:44Z",
            "updated_time": "2025-07-21T09:07:46.106427Z"
        },
       ... 
    ]
}

Edit a group of resource instances​

POST /api/iesn/edit_instances/

Add keywords, delete keywords, clear all keywords, or change text format for a group of resource instances.

Request body parameters:

  • ids

    A list of resource instance IDs to edit.

    Type: List

    Example: ["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"]

  • exclude_ids

    A list of resource instance IDs to exclude for editing.

    Type: List

    Example: ["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"]

  • system

    The system to which the resource instances belong (the parent system of the resource instances).

    Type: UUID (the string of the ID of a system) or String

    Example: c72b05b4-3949-4b1f-a583-15ce1f99185b

  • is_all

    Whether to edit all resource instances in the system.

    warning

    If is_all is true, the service will edit all of your resource instances in the system except the ones in exclude_ids.

    Type: Boolean

    Example: false

  • words_to_update_all

    If is_all is true and avoiding the wrong operations, the words_to_update_all should be the exact string: UPDATE ALL INSTANCES FOR <username> (Replace <username> by your username).

    Type: String

    Example: UPDATE ALL INSTANCES FOR auser

  • keywords_to_add

    A list of keywords to add.

    Type: List

    Example: ["keyword 1"]

  • keywords_to_delete

    A list of keywords to delete.

    Type: List

    Example: ["keyword 2"]

  • is_clear_keywords

    Whether to clear all keywords.

    warning

    If is_clear_keywords is true, the service will clear all keywords of selected resources.

    Type: Boolean

    Example: false

  • format

    The format of resource instance introduction to change.

    Type: Enumeration (one of the following values)

    • null

      Default format (you can set it on Settings page)

    • 1

      Plain text

    • 2

      Markdown

    Example: 2

  • search_params

    If wantting to edit or delete all resource instances by searching, you can use this parameter.

    is_all should be true in this situation.

    Refer to Search resource instances for the specific parameters.

    Type: Object or Dictionary

  • keyword_filter_params

    If wantting to edit or delete all resource instances by keyword filter, you can use this parameter.

    is_all should be true in this situation.

    Refer to Filter resource instances for the specific parameters.

    Type: Object or Dictionary

Example of request body:

{"ids":["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"],"is_all":false,"exclude_ids":[],"keywords_to_add":["keyword 1"],"keywords_to_delete":[],"is_clear_keywords":false,"format":0}

Successful response status code: 200

Move a group of resource instances​

POST /api/iesn/move_instances/

Move a group of resource instances to the destination system from the source system.

Request body parameters:

  • ids

    A list of resource instance IDs to move.

    Type: List

    Example: ["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"]

  • exclude_ids

    A list of resource instance IDs to exclude for moving.

    Type: List

    Example: ["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"]

  • src_system

    The source system of the resource instances to move.

    Type: UUID or string

    Example: 69cfa55a-24ef-4cba-9789-32b5844b36bc

  • dest_system

    The destination system.

    Type: UUID or string

    Example: 69cfa55a-24ef-4cba-9789-32b5844b36bc

  • new_order

    The new order in destination system.

    Type: Number

    Example: 1

  • is_all

    Whether to move all resource instances in the system.

    danger

    If is_all is true, the service will move all of your resource instances in the source system except the ones in exclude_ids.

    Type: Boolean

    Example: false

  • search_params

    If wantting to edit or delete all resource instances by searching, you can use this parameter.

    is_all should be true in this situation.

    Refer to Search resource instances for the specific parameters.

    Type: Object or Dictionary

  • keyword_filter_params

    If wantting to edit or delete all resource instances by keyword filter, you can use this parameter.

    is_all should be true in this situation.

    Refer to Filter resource instances for the specific parameters.

    Type: Object or Dictionary

Example of request body:

{"ids":["8cafea69-d897-4a91-b21d-39f03532e10c","1ad7ce99-b7c5-4f65-8eb5-a6f0779112f1"],"is_all":false,"exclude_ids":[],"src_system":"69cfa55a-24ef-4cba-9789-32b5844b36bc","dest_system":"c72b05b4-3949-4b1f-a583-15ce1f99185b","new_order":1}

Successful response status code: 200

Delete a group of resource instances​

POST /api/iesn/delete_instances/

Delete a group of resource instances permanently.

danger

This action will delete the selected resource instances, and the corresponding resources according to the option.

Request body parameters:

  • ids

    A list of resource instance IDs to delete.

    Type: List

    Example: ["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"]

  • exclude_ids

    A list of resource instance IDs to exclude for deleting.

    Type: List

    Example: ["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"]

  • system

    The parent system of the resource instances to delete.

    Type: UUID or string

    Example: 69cfa55a-24ef-4cba-9789-32b5844b36bc

  • is_all

    Whether to delete all resource instances in the system.

    danger

    If is_all is true, the service will delete all of your resource instances in the system except the ones in exclude_ids.

    Type: Boolean

    Example: false

  • words_to_delete_all

    If is_all is true and avoiding the wrong operations, the words_to_update_all should be the exact string: DELETE ALL INSTANCES FOR <username> (Replace <username> by your username).

    Type: String

    Example: DELETE ALL INSTANCES FOR auser

  • option

    Refer to the parameter option of Delete a resource instance.

  • search_params

    If wantting to move all resource instances by searching, you can use this parameter.

    is_all should be true in this situation.

    Refer to Search resource instances for the specific parameters.

    Type: Object or Dictionary

  • keyword_filter_params

    If wantting to move all resource instances by keyword filter, you can use this parameter.

    is_all should be true in this situation.

    Refer to Filter resource instances for the specific parameters.

    Type: Object or Dictionary

Example of request body:

{"ids":["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"],"is_all":false,"exclude_ids":[],"option":"with_resource_having_only_instance"}

Response format:

{"deleted_instances_number":2,"deleted_resources_number":0}

System​

Create a system​

POST /api/system/

Request body parameters:

  • parent

    The parent system of the new created system.

    Type: UUID (the string of the ID of a system) or String

    • none

      It means the ROOT system.

    Example: c72b05b4-3949-4b1f-a583-15ce1f99185b

  • name

    The name or title of the system.

    Type: String

    Example: Bookmarks

  • introduction

    The brief description of the system.

    Type: String

    Example: External bookmarks from Internet

  • keywords

    A list of keyword to describe the system.

    Type: List (["keyword_content", ...])

    Example: ["Bookmarks"]

  • order

    The system order of the new created system in the parent system.

    Type: Number or null

    • Number

      This is the exact order. If it is beyond zero or the max number of children in the parent system, the order will be the zero or the number of last item respectively.

    • null

      The field can be null and it means the new created system will be put into the last position.

    Example: 0

  • format

    The format of system introduction.

    Type: Enumeration (one of the following values)

    • null

      Default format (you can set it on Settings page)

    • 1

      Plain text

    • 2

      Markdown

    Example: 2

  • url

    The URL of the resource to be bound with the system .

    Type: String or null

    Example: https://metaessen.com/

Example of request body:

{"name":"New system","introduction":"This is a system for bookmarks","keywords":[],"order":null,"parent":"69cfa55a-24ef-4cba-9789-32b5844b36bc","format":null,"url":null}

Response format:

  • user_esn

    The bound resource.

    Refer to Retrieve a resource

  • child_system_count

    The number of child systems of the system.

  • instance_essences_count

    The number of child instances of the system.

{
    "id": "3db9ee8f-264f-44ea-862b-7aa6f8189702",
    "name": "New system",
    "introduction": "This is a system for bookmarks",
    "keywords": [],
    "order": 2,
    "format": null,
    "child_system_count": 0,
    "user_esn": null,
    "instance_essences_count": 0,
    "created_time": "2026-08-25T06:32:36.886456Z",
    "updated_time": "2026-08-25T06:32:36.888132Z"
}

Retrieve a system​

GET /api/system/<id>/

Retrieve a single system by ID.

Request URL parameters:

  • id

    The system ID.

    Type: UUID

    Example: b8377371-c7f6-495b-9f1e-0b5d2adbc37a

Response format:

{
    "id": "42cbaada-e938-40e8-b5a7-20695725be56",
    "name": "Documentation",
    "introduction": null,
    "keywords": [],
    "order": 8,
    "format": null,
    "child_system_count": 0,
    "user_esn": null,
    "instance_essences_count": 3,
    "created_time": "2025-09-03T16:26:50Z",
    "updated_time": "2026-06-12T02:53:58.523319Z"
}

Update a system​

PUT /api/system/<id>/
PATCH /api/system/<id>/

Update a system by ID.

The method PUT requires that all required fields must be provied, but PATCH has no the requirement and just update the provided fields.

name and parent fields are required now.

If any field is not provided, its value will not be changed.

Request URL parameters:

  • id

    The system ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Request body parameters (refer to Create a system).

  • name
  • introduction
  • keywords
  • order
  • format
  • url

Example of request body

{"name":"Docs","introduction":"","keywords":[],"order":8,"url":null}

Response format:

{
    "id": "42cbaada-e938-40e8-b5a7-20695725be56",
    "name": "Docs",
    "introduction": "",
    "keywords": [],
    "order": 8,
    "format": null,
    "child_system_count": 0,
    "user_esn": null,
    "instance_essences_count": 3,
    "created_time": "2025-09-03T16:26:50Z",
    "updated_time": "2026-08-25T06:45:36.143075Z"
}

Delete a system or system tree​

DELETE /api/system/<id>/
POST /api/system/delete_tree/

Delete a system or system tree by ID.

warning

These actions will delete the system, its all descendant systems, and all resource instances belonging to them.

Request URL parameters:

  • id

    The resource instance ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Request body parameters for /api/system/delete_tree/:

  • id

    The system ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

  • option

    Type: Enumeration (one of the following values)

    • tree

      Delete the whole tree.

    • descendants

      Delete descendant systems and resource instances except the root system.

    • descendant_instances

      Delete descentant resource instances except all systems in the tree.

      This is the default value.

    Example: with_resource_having_only_instance

  • option_for_instances

    Refer to Delete a resource instance

    Type: Enumeration (one of the following values)

    • instance
    • with_resource
    • with_resource_having_only_instance

Example of request body of /api/system/delete_tree/

{"id":"65f3d897-3be7-46b6-90e3-30fa381c4512","option":"tree","option_for_instances":"with_resource_having_only_instance"}

Response of /api/system/delete_tree/

{
    "deleted_systems_number": 1,
    "deleted_instances_number": 0,
    "deleted_resources_number": 0
}

Successful response status code of DELETE /api/system/<id>/: 204

List systems​

GET /api/system/

Get a list of systems.

Request URL query parameters:

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      -createdtime, -name, -updatedtime, -url, -path, createdtime, name, updatedtime, url, path

    • Default value: -createdtime

    Example: -name

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/system/?ordering=-createdtime&page=1

Response format:

{
    "count": 1733,
    "next": "https://metaessen.com/api/system/?ordering=-createdtime&page=2",
    "previous": null,
    "results": [
        {
            "id": "3db9ee8f-264f-44ea-862b-7aa6f8189702",
            "name": "New system",
            "introduction": "This is a system for bookmarks",
            "keywords": [],
            "order": 2,
            "format": null,
            "child_system_count": 0,
            "user_esn": null,
            "instance_essences_count": 0,
            "created_time": "2026-08-25T06:32:36.886456Z",
            "updated_time": "2026-08-25T06:32:36.888132Z"
        },
        ...
    ]
}

List child resource instances of a system​

POST /api/system/<id>/instances/

Request URL query parameters:

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      order, -order, url, -url, createdtime, -createdtime, name, -name, updatedtime, -updatedtime

    • Default value: order

    Example: -order

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/system/69cfa55a-24ef-4cba-9789-32b5844b36bc/instances/?ordering=order&page=1

Response format:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "562e3bca-632b-4b43-8761-e7eee87806d2",
            "system": "f15dcb78-e3ca-41e0-8b6f-ad78b216e698",
            "user_esn": {
                "id": "b885751d-2353-4af6-82f8-8c068e4180aa",
                "url": "https://developer.mozilla.org/en-US/docs/Glossary/Character_reference",
                "name": "Character reference - MDN Web Docs Glossary: Definitions of Web-related terms | MDN",
                "introduction": "An HTML character reference is an escape sequence of characters that is used to represent another character in the rendered web page.",
                "keywords": [],
                "format": 1,
                "system": null,
                "instance_count": 1,
                "created_time": "2025-02-05T14:06:36Z",
                "updated_time": "2025-07-21T09:04:45.427134Z"
            },
            "name": "",
            "introduction": null,
            "keywords": [],
            "order": 0,
            "format": null,
            "created_time": "2025-02-05T14:06:36Z",
            "updated_time": "2025-07-21T09:07:41.396671Z"
        },
        ...
    ]
}

List descendants of a system​

POST /api/system/<id>/descendants/

Get a list of descendant systems or resource instances of a system.

Request URL query parameters:

  • type

    Type: Enumeration

    • child_systems

      Get only child systems

    • children

      Get child systems and resource instances.

    • descendant_instances

      Get descendant resource instances.

    • descendant_systems

      Get descendant systems.

    • descendants

      Get descendant systems and resource instances.

    Default value: children

    Example: children

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      order, -order, url, -url, createdtime, -createdtime, name, -name, updatedtime, -updatedtime

    • Default value: order

    Example: -order

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/system/1998934c-5e24-4320-b313-465c33582b23/descendants/?ordering=-createdtime&page=1&type=descendants

Response format:

{
    "count": 6,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "562e3bca-632b-4b43-8761-e7eee87806d2",
            "name": "",
            "introduction": null,
            "order": 1,
            "format": null,
            "created_time": "2025-02-05T14:06:36Z",
            "updated_time": "2025-07-21T09:07:41.396671Z",
            "keywords": [],
            "user_esn": {
                "id": "b885751d-2353-4af6-82f8-8c068e4180aa",
                "url": "https://developer.mozilla.org/en-US/docs/Glossary/Character_reference",
                "name": "Character reference - MDN Web Docs Glossary: Definitions of Web-related terms | MDN",
                "introduction": "An HTML character reference is an escape sequence of characters that is used to represent another character in the rendered web page.",
                "keywords": [],
                "format": 1,
                "system": null,
                "instance_count": 1,
                "created_time": "2025-02-05T14:06:36Z",
                "updated_time": "2025-07-21T09:04:45.427134Z"
            },
            "url": "https://developer.mozilla.org/en-US/docs/Glossary/Character_reference",
            "system": "f15dcb78-e3ca-41e0-8b6f-ad78b216e698",
            "parent": null,
            "is_system": false
        },
        {
            "id": "f15dcb78-e3ca-41e0-8b6f-ad78b216e698",
            "name": "HTML",
            "introduction": null,
            "order": 1,
            "format": null,
            "created_time": "2025-02-05T13:43:25Z",
            "updated_time": "2025-07-08T15:18:31.881622Z",
            "keywords": [],
            "user_esn": null,
            "url": null,
            "system": null,
            "parent": "1998934c-5e24-4320-b313-465c33582b23",
            "is_system": true
        },
        ... 
    ]
}

Retrieve system tree​

POST /api/system/tree

Get the whole system tree.

Response format:

  • "id": null

    It means the ROOT system.

{
    "id": null,
    "name": "",
    "children": [
        {
            "id": "15da029f-edd4-4649-a087-f1c1730aa870",
            "name": "Article",
            "order": 3,
            "created_time": "2024-08-16T13:18:03Z",
            "updated_time": "2025-07-08T15:18:31.341745Z",
            "children": [
                {
                    "id": "64cc090d-4b16-47f0-9bd9-8d5788e15eb2",
                    "name": "React",
                    "order": 0,
                    "created_time": "2024-09-13T05:24:34Z",
                    "updated_time": "2025-07-08T15:18:31.353120Z",
                    "children": [
                        {
                            "id": "68823f25-2825-49f6-9473-f09a51e3365a",
                            "name": "Escape Hatches",
                            "order": 0,
                            "created_time": "2024-09-17T04:14:16Z",
                            "updated_time": "2025-07-08T15:18:31.360646Z",
                            "children": [
                                {
                                    "id": "08eb537d-dc87-42b7-9b43-97efff3a5264",
                                    "name": "You Might Not Need an Effect",
                                    "order": 0,
                                    "created_time": "2024-09-17T04:14:42Z",
                                    "updated_time": "2025-07-08T15:18:31.367998Z",
                                    "children": [
                                        {
                                            "id": "56ca4e64-069c-441f-baa6-8bf23e68b0e2",
                                            "name": "How to remove unnecessary Effects",
                                            "order": 0,
                                            "created_time": "2024-09-17T04:27:26Z",
                                            "updated_time": "2025-07-08T15:18:31.376136Z",
                                            "children": []
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                },
                {
                    "id": "515d95d9-3577-4ca0-8c58-2387e9c6dde7",
                    "name": "Django",
                    "order": 1,
                    "created_time": "2024-09-13T05:24:26Z",
                    "updated_time": "2025-07-08T15:18:31.394047Z",
                    "children": []
                },
                ...
            ]
        },
        ...
    ]
}

Copy a system or system tree​

POST /api/system/copy/

Request body parameters:

Refer to Create a system

  • parent

  • name

  • keywords

  • order

  • format

  • url

  • option

    Type: Enumeration (one of the following values)

    • only_root

      Just copy the root system of the tree.

    • tree

      Copy the whole system tree except resource instances.

    • root_and_instances

      Copy the root system and child resource instances of the root system.

    • tree_and_instances

      Copy the whole system tree and resource instances.

Example of request body:

{"name":"Asystem tree","introduction":null,"keywords":[],"order":null,"parent":"2e28815f-3663-4dc1-a41a-5d856198d2d9","url":null,"option":"tree"}

Response format:

{
    "dst_system": {
        "id": "d4933c5d-679a-474c-a105-88aef9080801",
        "name": "8898sdfsadklf4411",
        "introduction": null,
        "keywords": [],
        "order": 31,
        "format": null,
        "child_system_count": 0,
        "user_esn": null,
        "instance_essences_count": 0,
        "created_time": "2026-08-25T08:23:07.884669Z",
        "updated_time": "2026-08-25T08:23:07.889829Z"
    },
    "instances_count": 0,
    "systems_count": 0
}

Search systems​

POST /api/system/search/

Search systems by some string.

Request URL query parameters:

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/system/search/?page=1

Request body parameters:

  • search_string

    Type: String

    Example: markdown

  • system_tree

    Which system tree to search for resource instances.

    Type: UUID or String

    • none

      It means the ROOT system.

      Default value.

    • UUID

      A specific system which is the root of the sub system tree.

    Example: 69cfa55a-24ef-4cba-9789-32b5844b36bc

  • where

    The specific place in the system tree.

    Type: Enumeration (one of the following values)

    • root

      Just search the resource instances belonging to the root system.

    • descendants

      Search all resource instances belonging to descendant systems.

    • root_and_descendants

      Search all resource instances belonging to the root and descendant systems.

      Default value.

    • children

      Just search the resouce instances belonging to the child systems of the root system.

    Example: root_and_descendants

  • options

    Type: Dictionary or Object

    • case_sensitive

      Whether to think about the uppercase or lowercase of the search string.

      Type: Boolean

    • include_id

      Whether to search the resource and resource instance ID.

      Type: Boolean

    • include_name

      Whether to search the resource and resource instance name.

      Type: Boolean

    • include_introduction

      Whether to search the resource and resource instance introduction.

      Type: Boolean

    • include_keywords

      Whether to search the resource and resource instance keywords.

      Type: Boolean

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      -createdtime, -name, -updatedtime, -url, -path, createdtime, name, updatedtime, url, path

      • path

        The system path of a resource instance.

        Example: /Bookmarks

    • Default value: -createdtime

    Example: -name

Example of request body:

{"search_string":"django","system_tree":"none","where":"root_and_descendants","options":{"case_sensitive":false,"include_id":true,"include_name":true,"include_introduction":true,"include_keywords":true},"ordering":"-createdtime"}

Response format:

{
    "count": 13,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "aa63ed67-6c2a-4a95-931c-38a132f0b00a",
            "name": "Django REST framework",
            "introduction": null,
            "keywords": [],
            "order": 2,
            "format": null,
            "child_system_count": 0,
            "user_esn": null,
            "instance_essences_count": 2,
            "created_time": "2025-02-21T02:06:45Z",
            "updated_time": "2025-07-08T15:18:35.809548Z"
        },
        ...
    ]
}

Filter systems​

POST /api/system/keywords_filter/

Filter systems by keywords.

Request URL query parameters:

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/system/keywords_filter/?page=1

Request body parameters:

  • keywords

    A list of keyword to describe the resource.

    Type: List (["keyword_content", ...])

    Example: ["Bookmark manager"]

  • include_all

    Whether to include all keywords or just include any of keywords for filtered resource instances.

    Type: Boolean

    Example: true

  • system_tree

    Refer to Search resource instances

  • where

    Refer to Search resource instances

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      -createdtime, -name, -updatedtime, -url, -path, createdtime, name, updatedtime, url, path

    • Default value: -createdtime

    Example: -name

Example of request body:

{"keywords":[{"content":"python"}],"include_all":true,"system_tree":"none","where":"root_and_descendants","ordering":"-createdtime"}

Response format:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "06260083-b80a-4b4d-93cf-865886909360",
            "name": "Decorator",
            "introduction": "",
            "keywords": [
                {
                    "id": "6e3b6d9d-282b-4b5a-a576-5931b48a8920",
                    "content": "Python",
                    "bound_time": "2026-08-25T09:11:14.410819Z"
                }
            ],
            "order": 0,
            "format": null,
            "child_system_count": 0,
            "user_esn": null,
            "instance_essences_count": 1,
            "created_time": "2025-01-11T01:49:09Z",
            "updated_time": "2026-08-25T09:11:14.432697Z"
        }
    ]
}

Keyword​

Create a keyword​

POST /api/keywords/

Request body parameters:

  • content

    The content of the keyword.

    Type: String

    Example: Note-taking

Example of request body:

{"content":"Note taking"}

Response format:

{
    "id": "fcd69b8b-0cfe-42c4-9376-94e6da53ce57",
    "content": "Note taking",
    "created_time": "2026-08-25T09:39:14.284272Z",
    "updated_time": "2026-08-25T09:39:14.284669Z"
}

Retrieve a keyword​

GET /api/keywords/<id>/

Retrieve a single keyword by ID.

Request URL parameters:

  • id

    The keyword ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Response format:

  • related_systems_count

    The number of related systems.

  • related_resources_count

    The number of related resources.

  • related_instances_count

    The number of related resource instances.

{
    "id": "fcd69b8b-0cfe-42c4-9376-94e6da53ce57",
    "content": "Note taking",
    "related_systems_count": 0,
    "related_resources_count": 0,
    "related_instances_count": 0,
    "created_time": "2026-08-25T09:39:14.284272Z",
    "updated_time": "2026-08-25T09:39:14.284669Z"
}

Update a keyword​

PUT /api/keywords/<id>/
PATCH /api/keywords/<id>/

Update a keyword by ID.

The method PUT requires that all required fields must be provied, but PATCH has no the requirement and just update the provided fields.

content field is required now.

If any field is not provided, its value will not be changed.

Request URL parameters:

  • id

    The keyword ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Request body parameters (refer to Create a keyword).

Example of request body

{"content":"Note taking for tech"}

Response format:

{
    "id": "fcd69b8b-0cfe-42c4-9376-94e6da53ce57",
    "content": "Note taking for tech",
    "created_time": "2026-08-25T09:39:14.284272Z",
    "updated_time": "2026-08-25T09:44:47.328150Z"
}

Delete a keyword​

DELETE /api/keywords/<id>/

Delete a keywords by ID.

warning

This action will delete the keyword, and unbind related systems, resources or resource instances with it.

Request URL parameters:

  • id

    The keyword ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Successful response status code: 204

List keywords​

GET /api/keywords/

Get a list of keywords.

Request URL query parameters:

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      -content, -createdtime, -updatedtime, content, createdtime, updatedtime

    • Default value: -createdtime

    Example: -content

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/keywords/?ordering=-createdtime&page=1

Response format:

{
    "count": 418,
    "next": "https://metaessen.com/api/keywords/?ordering=-createdtime&page=2",
    "previous": null,
    "results": [
        {
            "id": "fcd69b8b-0cfe-42c4-9376-94e6da53ce57",
            "content": "Note taking",
            "created_time": "2026-08-25T09:39:14.284272Z",
            "updated_time": "2026-08-25T09:39:14.284669Z"
        },
        ...
    ]
}

List keyword content​

GET /api/keywords/contents/

Get the list of content of all keywords.

Response format:

[
    {
        "content": "Python"
    },
    {
        "content": "Django"
    },
    ...
]
POST /api/keywords/<id>/related_resources/
POST /api/keywords/<id>/related_instances/
POST /api/keywords/<id>/related_systems/

Get related resources, resource instances, or systems by keyword ID.

Request URL parameters:

  • id

    The keyword ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/keywords/16c8feb0-1593-4170-be49-26a39362bec9/related_instances/?page=1

Response format:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "22baa1c4-8ee9-476b-b72b-05a9b541ce6c",
            "system": "75d3e256-a978-4357-88a4-f2bbd4ca7557",
            "user_esn": {
                "id": "d0f9232c-cb89-4c2f-b595-8999f16e8ee7",
                "url": "https://en.wikipedia.org/wiki/Python_(programming_language)#Language_Development",
                "name": "Python (programming language) - Wikipedia",
                "introduction": "",
                "keywords": [],
                "format": 1,
                "system": null,
                "instance_count": 2,
                "created_time": "2025-05-07T04:35:57Z",
                "updated_time": "2025-07-21T09:04:54.346682Z"
            },
            "name": "The versions of CPython's public releases",
            "introduction": "",
            "keywords": [
                {
                    "id": "16c8feb0-1593-4170-be49-26a39362bec9",
                    "content": "Bug fix releases",
                    "bound_time": "2025-07-21T09:07:47Z"
                },
                {
                    "id": "4d424e29-c836-4122-83d9-9b36672b6062",
                    "content": "Major or \"feature\" releases",
                    "bound_time": "2025-07-21T09:07:47Z"
                }
            ],
            "order": 1,
            "format": null,
            "created_time": "2025-05-07T04:35:57Z",
            "updated_time": "2026-06-16T16:43:43.436383Z"
        },
        ...
    ]
}

Search keywords​

POST /api/keywords/search/

Search keywords by some string.

Request URL query parameters:

  • page

    Type: Number

    • Default value: 1

    Example: 1

Example of the request URL:

https://metaessen.com/api/keywords/search/?page=1

Request body parameters:

  • search_string

    Type: String

    Example: cache

  • options

    Type: Dictionary or Object

    • case_sensitive

      Whether to think about the uppercase or lowercase of the search string.

      Type: Boolean

    • include_id

      Whether to search the ID.

      Type: Boolean

    • include_content

      Whether to search the content.

      Type: Boolean

  • ordering

    Type: Enumeration

    • Available values (a value starting a minus - means descending)

      -createdtime, -content, -updatedtime, createdtime, content, updatedtime

    • Default value: -createdtime

    Example: -content

Example of request body:

{"search_string":"bug","options":{"case_sensitive":false,"include_id":false,"include_content":true},"ordering":"-createdtime"}

Response format:

{
    "count": 4,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "16c8feb0-1593-4170-be49-26a39362bec9",
            "content": "Bug fix releases",
            "created_time": "2025-07-21T09:07:47.098014Z",
            "updated_time": "2025-07-21T09:07:47.098143Z"
        },
        ...
    ]
}

Delete a group of keywords​

POST /api/keywords/delete_keywords/

Delete a group of keywords permanently.

danger

This action will delete the keywords, and unbind related systems, resources or resource instances with them.

Request body parameters:

  • ids

    A list of keyword IDs to delete.

    Type: List

    Example: ["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"]

  • exclude_ids

    A list of keyword IDs to exclude for deleting.

    Type: List

    Example: ["ab61aea0-a359-4f50-a862-99e99bbe81d6","d429e745-3932-4c00-848f-8be71c5f45dc"]

  • is_all

    Whether to delete all keywords.

    danger

    If is_all is true, the service will delete all of your keywords except the ones in exclude_ids.

    Type: Boolean

    Example: false

  • words_to_delete_all

    If is_all is true and avoiding the wrong operations, the words_to_update_all should be the exact string: DELETE ALL KEYWORDS FOR <username> (Replace <username> by your username).

    Type: String

    Example: DELETE ALL RESOURCES FOR auser

  • search_params

    If wantting to delete all keywords by searching, you can use this parameter.

    is_all should be true in this situation.

    Refer to Search keywords for the specific parameters.

    Type: Object or Dictionary

Example of request body:

{"ids":[{"id":"642b2197-e9f6-40e8-aca0-ea42aa63d767"},{"id":"ddf6ca0c-ed2d-446c-92e0-ccf8ba1a8cfd"}],"is_all":false,"exclude_ids":[]}

Response format:

{"deleted_keywords_number":2}

Settings​

Retrieve settings​

GET /api/settings/mine/

Get your settings.

Response format:

Refer to Update settings.

  • format
  • default_system_path
  • update_existing_entity
{
    "id": "ed4e1fda-64fd-4dcd-b9a1-b7e12c049c23",
    "format": 2,
    "default_system_path": "/test1/11",
    "update_existing_entity": 1
}

Update settings​

PUT /api/settings/<id>/
PATCH /api/settings/<id>/

Update the settings by ID.

The method PUT requires that all required fields must be provied, but PATCH has no the requirement and just update the provided fields.

No field is required now.

If any field is not provided, its value will not be changed.

Request URL parameters:

  • id

    The settings ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Request body parameters:

  • format

    The default text format in website level.

    Type: Enumeration

    • 1

      Plain text.

    • 2

      Markdown.

  • default_system_path

    The default system path for bookmarked resource instance for bookmarklets settings.

    Type: String

  • update_existing_entity

    Whether to update the existing resource or instance for bookmarklets settings.

    Type: Enumeration

    • 1

      No and return. If there is an error, the service will return the error to the bookmarklet.

    • 2

      No and ignore.

    • 3

      Do it anyway.

Example of request body

{"default_system_path":"/Bookmarks","update_existing_entity":1}

Response format:

{
    "id": "ed4e1fda-64fd-4dcd-b9a1-b7e12c049c23",
    "format": 2,
    "default_system_path": "/Bookmarks",
    "update_existing_entity": 1
}

User​

Retrieve user profile​

GET /api/user/me/

Get your profile.

Response format:

{
    "id": "2d58ba57-8cb0-4c9d-bbec-0ad8c974ca81",
    "username": "micheal",
    "first_name": "Micheal",
    "last_name": "Sun",
    "plan": "Basic discount ($30.00 / Year)",
    "subscribed": true,
    "closed": false,
    "subscription_start_date": "2025-10-13T06:14:57Z",
    "subscription_end_date": "2129-10-13T06:14:57Z",
    "registration_date": "2024-08-11T07:19:42Z"
}

Update user profile​

PUT /api/user/<id>/
PATCH /api/esn/<id>/

Update the profile of a user by ID.

The method PUT requires that all required fields must be provied, but PATCH has no the requirement and just update the provided fields.

No field is required now.

If any field is not provided, its value will not be changed.

Request URL parameters:

  • id

    The user ID.

    Type: UUID

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Request body parameters:

  • username
  • first_name
  • last_name

Example of request body

{"username":"ausername"}

Response format:

{
    "id": "2d58ba57-8cb0-4c9d-bbec-0ad8c974ca81",
    "username": "micheal",
    "first_name": "Micheal",
    "last_name": "Sun",
    "plan": "Basic discount ($30.00 / Year)",
    "subscribed": true,
    "closed": false,
    "subscription_start_date": "2025-10-13T06:14:57Z",
    "subscription_end_date": "2129-10-13T06:14:57Z",
    "registration_date": "2024-08-11T07:19:42Z"
}

Retrieve data statistics​

POST /api/user/data_stats/

Get the statistics of you all data.

Response format:

  • systems_count

    Total number of systems

  • resources_count

    Total number of resources

  • instances_count

    Total number of instances

  • keywords_count

    Total number of keywords

  • keywords_for_systems_count

    Total number of all keywords used for systems

  • different_keywords_for_systems_count

    Total number of different keywords used for systems

  • keywords_for_resources_count

    Total number of all keywords used for resources

  • different_keywords_for_resources_count

    Total number of different keywords used for resources

  • keywords_for_instances_count

    Total number of all keywords used for instances

  • different_keywords_for_instances_count

    Total number of different keywords used for instances

{
    "resources_count": 4712,
    "instances_count": 9196,
    "systems_count": 1736,
    "keywords_count": 415,
    "keywords_for_resources_count": 349,
    "keywords_for_instances_count": 664,
    "keywords_for_systems_count": 858,
    "different_keywords_for_resources_count": 205,
    "different_keywords_for_instances_count": 148,
    "different_keywords_for_systems_count": 12
}