{"id":13787364,"url":"https://github.com/NodeBB/nodebb-plugin-write-api","last_synced_at":"2025-05-12T00:30:54.732Z","repository":{"id":21127053,"uuid":"24427934","full_name":"NodeBB/nodebb-plugin-write-api","owner":"NodeBB","description":"A RESTful JSON-speaking API allowing you to write things to NodeBB","archived":false,"fork":false,"pushed_at":"2025-05-10T17:35:04.000Z","size":891,"stargazers_count":134,"open_issues_count":17,"forks_count":74,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-10T18:28:22.444Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NodeBB.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-09-24T18:46:25.000Z","updated_at":"2025-05-10T17:34:20.000Z","dependencies_parsed_at":"2023-02-10T19:00:28.318Z","dependency_job_id":"35bfbf79-7370-4e79-b9e3-276a0be112dd","html_url":"https://github.com/NodeBB/nodebb-plugin-write-api","commit_stats":null,"previous_names":["julianlam/nodebb-plugin-write-api"],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NodeBB%2Fnodebb-plugin-write-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NodeBB%2Fnodebb-plugin-write-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NodeBB%2Fnodebb-plugin-write-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NodeBB%2Fnodebb-plugin-write-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NodeBB","download_url":"https://codeload.github.com/NodeBB/nodebb-plugin-write-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253655789,"owners_count":21943068,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T20:00:33.230Z","updated_at":"2025-05-12T00:30:52.656Z","avatar_url":"https://github.com/NodeBB.png","language":"JavaScript","readme":"# Deprecation\n\nAs of NodeBB v1.15.0, this plugin is deprecated and has entered maintenance mode. You can of course still use this plugin with versions of v1.15.x and beyond, and I will continue to ensure it is compatible; however new features will not be added.\n\n[Please see this blog post for more information](https://blog.nodebb.org/api-continues-to-evolve/)\n\nNew users are recommended to use [the built-in Write API](https://docs.nodebb.org/api/write) that comes with NodeBB v1.15.0 and up.\n\n# Write API\n\nThis plugin exposes a *write enabled API interface* for NodeBB. It is useful if you would like to supplment the built-in *read-only* API, in order to push items/actions/events to NodeBB.\n\nFor example, without this plugin, one can easily retrieve the contents of a post by prefixing `api/` to the corresponding route. (e.g. https://community.nodebb.org/api/topic/687/help-translate-nodebb/2).\n\nWith this plugin, however, you can create content on NodeBB externally (new topics, new posts, etc), which comes in handy when third-party applications want deeper integration with NodeBB.\n\n# Installation\n\n**Install this plugin via the plugins page in the ACP.**\n\nAlternatively:\n\n```\n$ cd /path/to/nodebb/node_modules\n$ git clone git@github.com:NodeBB/nodebb-plugin-write-api.git\n$ cd nodebb-plugin-write-api\n$ npm i\n```\n\nIn both methods, you will need to `./nodebb build` before (re-)starting your NodeBB forum.\n\n# API Resources\n\n* [`api/v1` Endpoints](routes/v1/readme.md)\n* [`api/v2` Endpoints](routes/v2/readme.md)\n\n# Quick Start\n\n1. Install and activate the plugin, reload NodeBB\n1. Generate your uid an API token in the ACP page\n1. `curl -H \"Authorization: Bearer {YOUR_TOKEN}\" --data \"title={TITLE}\u0026content={CONTENT}\u0026cid={CID}\" http://localhost:4567/api/v1/topics`\n\n# Authentication\n\nAuthentication is handled either via HTTP Bearer Token or JSON Web Token, as generated/specified in the Write API.\n\n## Bearer Tokens\n\nThere are two types of tokens:\n  * A *user token* is associated with a specific uid, and all calls made are made in the name of that user\n  * A *master token* is not associated with any specific uid, though a `_uid` parameter is required in the request, and then all calls are made in the name of *that* user.\n    This is the only difference between the two tokens. A master token with `_uid` set to a non-administrator will not allow you to make administrative calls.\n\n*Note*: The first token can be generated via the administration page (`admin/plugins/write-api`), or via the token generation route (`POST /api/v1/users/{UID}/tokens`) by sending in a password, but additional *user* tokens can be generated using an existing user/master token.\n\n## JSON Web Tokens\n\nJSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.\n\nTo make requests with a JSON Web Token instead of a user/master token, sign the entire request payload with the same secret as defined in the plugin, and either send it in the POST body, or as a query string parameter. In both cases, the key `token` is used.\n\nFor example,\n\n``` bash\n$ curl http://localhost:4567/api/v1/users/1/tokens?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfdWlkIjoxfQ.pbm5wbAZ4__yFh5y8oeCsJyT0dm8ROcd5SEBr4yGlNw  # secret is 'secret'\n```\n\n# Error Handling\n\nWhen the API encounters an error, it will do it's best to report what went wrong. Errors will follow the format specified in this example:\n\n    {\n        \"code\": \"not-authorised\",\n        \"message\": \"You are not authorised to make this call\",\n        \"params\": {}\n    }\n\n# Changelog\n\n## v5.0\n\n* Introduced v2 router with breaking changes to some routes (see [`api/v2` Endpoints](routes/v2/readme.md) for more information)\n* Additional validation for post routes in v2 router only\n\n## v4.6\n\n* Bug fixes\n* Allowing users to generate token via password input (only in token generation route)\n\n## v4.5\n\n* Bug fixes\n* Updated integration with NodeBB so that privileged assets in NodeBB (e.g. `/unread`) can be retrieved for a user via user/master tokens\n\n## v4.2\n\n* Fix bug with topic deletion\n* Introduced support for category enable/disable, and category purge (deletion)\n\n## v4.1\n\n* Allow addition of tags when creating topics\n* Handling post deletion via API\n\n## v3.x to v4.x\n\n* Made compatible with NodeBB v1.0.0\n\n## v3.1\n\n* Introduced support for JSON Web Tokens\n\n## v2.x to v3.x\n\n* `users/` routes now take a uid instead of a userslug. This affects the following routes:\n    * `PUT /api/v1/users/:userslug` -\u003e `PUT /api/v1/users/:uid`\n    * `POST /api/v1/users/:userslug/follow` -\u003e `POST /api/v1/users/:uid/follow`\n    * `DELETE /api/v1/users/:userslug/follow` -\u003e `DELETE /api/v1/users/:uid/follow`\n","funding_links":[],"categories":["Plugins"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNodeBB%2Fnodebb-plugin-write-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNodeBB%2Fnodebb-plugin-write-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNodeBB%2Fnodebb-plugin-write-api/lists"}