### Basic run example

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/server.js.md

Installs dependencies, starts the server, and verifies the live conversion of openapi.yml.

```bash
npm install
node server.js
curl -s http://localhost:3001/openapifile | jq '.info.title'
# "Discourse API Documentation"
```

--------------------------------

### Run local API docs server

Source: https://github.com/discourse/discourse_api_docs/blob/main/README.md

Install dependencies and start the local API docs server. Browse to http://localhost:3001 to view the pretty docs.

```bash
npm install
node server.js
```

--------------------------------

### Example JSON response for GET /site/basic-info.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/site.md

Example JSON response from the /site/basic-info.json endpoint, showing the fields 'title', 'description', and 'login_required' with sample values. This is the output of the preceding curl command.

```json
{ "title": "Discourse", "description": "A place for discussion", "login_required": false }
```

--------------------------------

### Basic run: install gem and execute script

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/to_json.rb.md

Shows how to install the required gem and run the script from the repo root. After execution, `openapi.json` is created as a pretty-printed, dereferenced spec.

```bash
gem install json_schema_ref_parser
ruby to_json.rb
ls -l openapi.json   # pretty-printed, dereferenced spec
```

--------------------------------

### GET /notifications.json - example response

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/notifications.md

Example JSON response for the GET notifications endpoint. Shows the structure of the notifications array and pagination fields.

```json
{
  "notifications": [
    {
      "id": 1,
      "notification_type": 6,
      "read": false,
      "created_at": "2024-01-01T00:00:00.000Z",
      "post_number": 1,
      "topic_id": 42,
      "fancy_title": "Hello world",
      "slug": "hello-world",
      "data": { "topic_title": "Hello world", "original_post_id": 1, "original_post_type": 1, "original_username": "sam", "display_username": "sam" }
    }
  ],
  "total_rows_notifications": 1,
  "seen_notification_id": 1,
  "load_more_notifications": "/notifications.json?offset=1"
}
```

--------------------------------

### Launch the documentation site

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/server.js.md

Command to start the development server and access the documentation site locally.

```bash
npm start
# -> "listening on http://localhost:3001"
# browse to http://localhost:3001  (serves local.html; ReDoc fetches /openapifile)
```

--------------------------------

### Example: toschema.js with topic response

Source: https://github.com/discourse/discourse_api_docs/blob/main/README.md

Example usage of toschema.js that converts a JSON response into JSON schema and then converts the schema to yml.

```bash
node toschema.js responses/topics/topic_respones.json definitions/topics/topic_response.yml
```

--------------------------------

### Error-handling example: missing input file

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/to_json.rb.md

Demonstrates the behavior when `openapi.yml` is missing. The script raises an `Errno::ENOENT` traceback. The example moves the file away, runs the script, and restores it.

```bash
mv openapi.yml /tmp/
ruby to_json.rb
# Traceback ... Errno::ENOENT: No such file or directory @ rb_sysopen - openapi.yml
mv /tmp/openapi.yml .
```

--------------------------------

### GET /admin/users.json - List users

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/users.md

Example of using curl to list users with administrative filters applied.

```bash
curl -X GET "https://discourse.example.com/admin/users.json?order=created&show_emails=true&page=1" \
  -H "Api-Key: YOUR_ADMIN_API_KEY" -H "Api-Username: system"
```

--------------------------------

### Basic run via npm

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/tobruno.js.md

Standard workflow for installing dependencies and executing the conversion script.

```bash
npm install
npm run tojson && npm run tobruno
# stdout: OpenAPI JSON conversion successful!
# bruno-collection.json now contains the full endpoint collection
```

--------------------------------

### Error-handling example (missing spec file)

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/server.js.md

Demonstrates the server behavior when the required openapi.yml file is missing.

```bash
mv openapi.yml /tmp/
node server.js
curl -s http://localhost:3001/openapifile   # request crashes; stderr shows:
# Error: ENOENT: no such file or directory, open 'openapi.yml'
```

--------------------------------

### PUT /notifications/mark-read.json - example response

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/notifications.md

Example JSON response for the mark-read endpoint, returning a success string.

```json
{ "success": "OK" }
```

--------------------------------

### Verification workflow

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/tojson.js.md

Runs the conversion and then starts the server in json mode, which can be browsed at http://localhost:3001.

```bash
node tojson.js && node server.js json
```

--------------------------------

### Example response for user badges

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/badges.md

Example JSON response for the user badges endpoint, showing empty arrays for badges, badge_types, granted_bies, and user_badges.

```json
{ "badges": [], "badge_types": [], "granted_bies": [], "user_badges": [] }
```

--------------------------------

### GET / route handler

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/server.js.md

Serves the local.html file which contains the ReDoc shell for the API documentation.

```javascript
app.get("/", function (req, res) {
  res.sendFile(__dirname + "/local.html");
});
```

--------------------------------

### Reuse in a custom script

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/tobruno.js.md

Example of how to replicate the conversion pipeline in a custom script with explicit error handling.

```js
const { openApiToBruno } = require("@usebruno/converters");
const { readFile, writeFile } = require("fs/promises");

async function regenerate(inputFile, outputFile) {
  try {
    const spec = JSON.parse(await readFile(inputFile, "utf8"));
    await writeFile(outputFile, JSON.stringify(openApiToBruno(spec), null, 2));
    return true;
  } catch (error) {
    console.error("OpenAPI → Bruno conversion failed:", error);
    throw error; // fail loudly in consumer code
  }
}
```

--------------------------------

### Express route handler for GET /openapifile

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/server.js.md

Handles GET requests to `/openapifile`. Reads `openapi.json` if the first CLI argument is `"json"`, otherwise reads `openapi.yml`. Parses the file, dereferences it with `refParser`, and sends the schema as JSON. On dereference error, logs to console and sends no response.

```javascript
app.get("/openapifile", function (req, res) {
  if (args[0] == "json") {
    fs.readFile("openapi.json", "utf8", function (err, data) {
      var json = JSON.parse(data);
      if (err) throw err;
      refParser.dereference(json, function (err, schema) {
        if (err) {
          console.error(err);
        } else {
          res.send(schema);
        }
      });
    });
  } else {
    fs.readFile("openapi.yml", "utf8", function (err, data) {
      if (err) throw err;
      var json = yaml.parse(data);
      refParser.dereference(json, function (err, schema) {
        if (err) {
          console.error(err);
        } else {
          res.send(schema);
        }
      });
    });
  }
});
```

--------------------------------

### GET /admin/backups/{filename}

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/backups.md

Downloads a backup file. Requires a filename path parameter and a token query parameter.

```APIDOC
## GET /admin/backups/{filename}

### Description
Download backup.

### Method
GET

### Endpoint
/admin/backups/{filename}

### Parameters
#### Path Parameters
- **filename** (string) - Required - The backup filename.

#### Query Parameters
- **token** (string) - Required - Download token.

### Response
#### Success Response (200)
Binary response; no schema. (Consumer: the backup file stream.)
```

--------------------------------

### Verify the committed JSON artifact

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/server.js.md

Starts the server in JSON mode to load openapi.json directly and verifies the path count.

```bash
node server.js json
curl -s http://localhost:3001/openapifile | jq '.paths | keys | length'
```

--------------------------------

### curl GET /topics/private-messages-sent/{username}.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/private-messages.md

Fetches the private messages sent folder for a user. The response includes a users array. The example pipes the output to jq to extract the username of the first user.

```bash
curl -X GET "https://discourse.example.com/topics/private-messages-sent/sam.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" | jq '.users[0].username'
```

--------------------------------

### curl GET /topics/private-messages/{username}.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/private-messages.md

Fetches the private messages inbox for a user. The response uses the shared topic-list envelope. The example pipes the output to jq to extract the title of the first topic.

```bash
curl -X GET "https://discourse.example.com/topics/private-messages/sam.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" | jq '.topic_list.topics[0].title'
```

--------------------------------

### app.listen method implementation

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/server.js.md

Initializes the server on port 3001 with a callback function that logs the listening status.

```js
app.listen(3001, function () {
  console.log("listening on http://localhost:3001");
});
```

--------------------------------

### Basic conversion usage

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/tojson.js.md

Installs dependencies and runs the conversion. The output shows the success message and a diff command to verify the info block matches between openapi.json and openapi.yml.

```bash
npm install
npm run tojson
# stdout: yml converted to json
diff <(jq '.info' openapi.json) <(python3 -c "import yaml,sys;print(yaml.safe_load(open('openapi.yml'))['info'])") || true
# openapi.json now contains the same info block as openapi.yml
```

--------------------------------

### curl example for GET /t/{id}.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/topics.md

Use this curl command to fetch a single topic by ID. It requires an API key and username, and pipes the JSON response to jq to extract the title and posts_count fields.

```bash
curl -X GET "https://discourse.example.com/t/42.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" | jq '.title, .posts_count'
```

--------------------------------

### GET /tags.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/tags.md

Get a list of tags. No parameters are required.

```APIDOC
## GET /tags.json

### Description
Get a list of tags.

### Method
GET

### Endpoint
/tags.json

### Parameters
None.

### Response
#### Success Response (200)
- **tags** (array<object>) - Optional
- **extras** (object) - Optional

#### Response Example
{
  "tags": [],
  "extras": {}
}

### Example
```bash
curl -X GET "https://discourse.example.com/tags.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system"
```
```

--------------------------------

### GET /t/{id}/posts.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/topics.md

Gets specific posts from a topic.

```APIDOC
## [GET] /t/{id}/posts.json

### Description
Gets specific posts from a topic.

### Method
GET

### Endpoint
/t/{id}/posts.json

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the topic.

#### Request Body
- **post_ids[]** (integer) - Required - The IDs of the posts to retrieve.

### Request Example
{
  "post_ids[]": [1, 2, 3]
}

### Response
#### Success Response (200)
- **post_stream** (object) - The post stream data.
- **id** (integer) - The topic ID.

#### Response Example
{
  "post_stream": {},
  "id": 42
}
```

--------------------------------

### GET /tag_groups.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/tags.md

Get a list of tag groups. No parameters are required.

```APIDOC
## GET /tag_groups.json

### Description
Get a list of tag groups.

### Method
GET

### Endpoint
/tag_groups.json

### Parameters
None.

### Response
#### Success Response (200)
- **tag_groups** (array<object>) - Required

#### Response Example
{
  "tag_groups": []
}
```

--------------------------------

### Module initialization in server.js

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/server.js.md

Initializes the Express application and required dependencies for the local documentation server.

```javascript
var express = require("express");
var app = express();
var yaml = require("yamljs");
var fs = require("fs");
var refParser = require("json-schema-ref-parser");
var args = process.argv.slice(2);
```

--------------------------------

### GET /directory_items.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/users.md

Get a public list of users. This endpoint returns directory items with metadata.

```APIDOC
## GET /directory_items.json

### Description
Get a public list of users.

### Method
GET

### Endpoint
/directory_items.json

### Parameters
#### Query Parameters
- **period** (string) - Required - enum: `daily`, `weekly`, `monthly`, `quarterly`, `yearly`, `all`
- **order** (string) - Required - enum: `likes_received`, `likes_given`, `topic_count`, `post_count`, `topics_entered`, `posts_read`, `days_visited`
- **asc** (string) - Optional - enum: [`true`]
- **page** (integer) - Optional - 

### Response
#### Success Response (200)
- **directory_items** (array<object>) - Required
- **meta** (object) - Required

```

--------------------------------

### Error-handling example for missing input

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/tobruno.js.md

Demonstrates how the script behaves when the input file is missing, noting that the exit code remains 0.

```bash
node -e "require('fs/promises').rename('openapi.json','openapi.json.bak')"
npm run tobruno
# stderr: Error during OpenAPI JSON conversion: Error: ENOENT: no such file or directory, open 'openapi.json'
# exit code: 0 (stderr must be monitored)
```

--------------------------------

### GET /user_actions.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/users.md

Get a list of user actions. This endpoint returns user actions for a specified user.

```APIDOC
## GET /user_actions.json

### Description
Get a list of user actions.

### Method
GET

### Endpoint
/user_actions.json

### Parameters
#### Query Parameters
- **offset** (integer) - Required - 
- **username** (string) - Required - 
- **filter** (string) - Required - 

### Response
#### Success Response (200)
- **user_actions** (array<object>) - Required

```

--------------------------------

### Create a user with curl (POST /users.json)

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/users.md

Use this curl command to create a new user. It requires an API key and username in the headers. The request body must include name, email, password, and username. The 'active' field is ignored unless an admin API key is provided.

```bash
curl -X POST "https://discourse.example.com/users.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" -H "Content-Type: application/json" \
  -d '{"name":"Sam Saffron","email":"sam@example.com","password":"supersecret","username":"sam"}'
```

--------------------------------

### GET /tag_groups/{id}.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/tags.md

Get a single tag group by ID. The ID is provided as a path parameter.

```APIDOC
## GET /tag_groups/{id}.json

### Description
Get a single tag group.

### Method
GET

### Endpoint
/tag_groups/{id}.json

### Parameters
#### Path Parameters
- **id** (string) - Required - The tag group ID.

### Response
#### Success Response (200)
- **tag_group** (object) - Optional

#### Response Example
{
  "tag_group": {}
}
```

--------------------------------

### Basic conversion execution

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/toschema.js.md

Run the script by providing an input JSON file and an output YAML file path. The command outputs a confirmation message and creates the schema file.

```bash
node toschema.js responses/search/query_response.json definitions/search/query_response.yml
# stdout: converted json response to yml schema
head -5 definitions/search/query_response.yml
```

--------------------------------

### GET /tag/{name}.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/tags.md

Get a specific tag by name. The tag name is provided as a path parameter.

```APIDOC
## GET /tag/{name}.json

### Description
Get a specific tag.

### Method
GET

### Endpoint
/tag/{name}.json

### Parameters
#### Path Parameters
- **name** (string) - Required - The tag name.

### Response
#### Success Response (200)
- **users** (array<object>) - Optional
- **primary_groups** (array) - Optional
- **topic_list** (object) - Optional

#### Response Example
{
  "users": [],
  "primary_groups": [],
  "topic_list": {}
}

### Example
```bash
curl -X GET "https://discourse.example.com/tag/design.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system"
```
```

--------------------------------

### POST /uploads/create-multipart.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/uploads.md

Initializes a multipart external upload by providing the upload type, file name, and file size in bytes.

```bash
curl -X POST "https://discourse.example.com/uploads/create-multipart.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" -H "Content-Type: application/json" \
  -d '{"upload_type":"composer","file_name":"big.zip","file_size":10485760}'
```

--------------------------------

### GET /groups/{name}.json — Get a group

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/groups.md

Retrieves a single group by its name. The group name is provided as a path parameter.

```APIDOC
## GET /groups/{name}.json

### Description
Get a group.

### Method
GET

### Endpoint
/groups/{name}.json

### Parameters
#### Path Parameters
- **name** (string) - Required - Use group name instead of id

### Response
#### Success Response (200)
- **group** (object) - Required
- **extras** (object) - Required

#### Response Example
```json
{
  "group": {},
  "extras": {}
}
```

### Example
```bash
curl -X GET "https://discourse.example.com/groups/moderators.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system"
```
```

--------------------------------

### Download backup with GET /admin/backups/{filename}

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/backups.md

Downloads a specific backup file. Requires the filename in the path and a valid token as a query parameter.

```bash
curl -X GET "https://discourse.example.com/admin/backups/2024-01-01-000000-v20240101000000.tar.gz?token=YOUR_TOKEN" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" -o backup.tar.gz
```

--------------------------------

### GET /groups/by-id/{id}.json — Get a group by id

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/groups.md

Retrieves a single group by its numeric ID. The ID is provided as a path parameter.

```APIDOC
## GET /groups/by-id/{id}.json

### Description
Get a group by id.

### Method
GET

### Endpoint
/groups/by-id/{id}.json

### Parameters
#### Path Parameters
- **id** (string) - Required - (description in spec: "Use group name instead of id")

### Response
#### Success Response (200)
- **group** (object) - Required
- **extras** (object) - Required

#### Response Example
```json
{
  "group": {},
  "extras": {}
}
```
```

--------------------------------

### Create multiple invites with curl (POST /invites/create-multiple.json)

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/invites.md

Example curl command to create multiple invites in one request. The email field contains multiple email addresses separated by spaces. Requires Api-Key and Api-Username headers. The response reports the number of successful and failed invitations.

```bash
curl -X POST "https://discourse.example.com/invites/create-multiple.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" -H "Content-Type: application/json" \
  -d '{"email":"a@example.com b@example.com","topic_id":42}'
```

--------------------------------

### GET /t/external_id/{external_id}.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/topics.md

Documentation for the GET /t/external_id/{external_id}.json endpoint, which retrieves a topic by its external ID and redirects to the canonical topic endpoint.

```APIDOC
## GET /t/external_id/{external_id}.json

### Description
Get topic by external_id. This endpoint redirects to the canonical topic endpoint.

### Method
GET

### Endpoint
/t/external_id/{external_id}.json

### Parameters
#### Path Parameters
- **external_id** (string) - Required - The external ID of the topic.

### Response
#### Success Response (301)
Redirects to /t/{topic_id}.json. No response body schema. Consumer code must follow the redirect to GET /t/{topic_id}.json.

### Request Example
```bash
curl -s -o /dev/null -w "%{redirect_url}\n" "https://discourse.example.com/t/external_id/ext-123.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system"
```
```

--------------------------------

### GET /topics/private-messages/{username}.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/private-messages.md

Get a list of private messages for a user. This endpoint returns the user's private message inbox with a topic_list envelope and sidecar arrays.

```APIDOC
## GET /topics/private-messages/{username}.json

### Description
Get a list of private messages for a user.

### Method
GET

### Endpoint
/topics/private-messages/{username}.json

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user whose private messages to retrieve.

### Response
#### Success Response (200)
- **users** (array<object>) - Optional - List of users.
- **primary_groups** (array) - Optional - List of primary groups.
- **topic_list** (object) - Optional - The topic list envelope.

The topic_list envelope contains fields: can_create_topic (boolean), draft (null), draft_key (string), draft_sequence (number), per_page (number), topics (array). Each topic item includes fields such as id, title, fancy_title, slug, posts_count, reply_count, highest_post_number, created_at, last_posted_at, bumped, bumped_at, unseen, last_read_post_number, unread, new_posts, pinned, visible, closed, archived, notification_level, bookmarked, liked, views, like_count, has_summary, archetype, last_poster_username, pinned_globally.

#### Response Example
```json
{
  "users": [],
  "primary_groups": [],
  "topic_list": {
    "can_create_topic": true,
    "draft": null,
    "draft_key": "",
    "draft_sequence": 0,
    "per_page": 30,
    "topics": []
  }
}
```

### Example
```bash
curl -X GET "https://discourse.example.com/topics/private-messages/sam.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" | jq '.topic_list.topics[0].title'
```
```

--------------------------------

### Create upload with curl

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/uploads.md

Synchronous upload example for POST /uploads.json. Uses multipart/form-data with fields type, user_id, synchronous, and file. Requires Api-Key and Api-Username headers.

```bash
curl -X POST "https://discourse.example.com/uploads.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" \
  -F "type=avatar" -F "user_id=1" -F "synchronous=true" \
  -F "file=@/path/to/avatar.png"
```

--------------------------------

### Create a single invite with curl (POST /invites.json)

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/invites.md

Example curl command to create an invite via the Discourse API. Requires an Api-Key and Api-Username header. The request body includes email, topic_id, and group_names. The response returns the invitation details.

```bash
curl -X POST "https://discourse.example.com/invites.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" -H "Content-Type: application/json" \
  -d '{"email":"newuser@example.com","topic_id":42,"group_names":"moderators"}'
```

--------------------------------

### Get specific posts from a topic with curl (GET /t/{id}/posts.json)

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/topics.md

Sends a POST request to retrieve specific posts from a topic, using the Api-Key and Api-Username headers. The request body includes an array of post IDs. The response is 200 with a post_stream object and an id. Note: the operation is declared as get in openapi.yml but includes a request body.

```bash
curl -X POST "https://discourse.example.com/t/42/posts.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" -H "Content-Type: application/json" \
  -d '{"post_ids[]":[1,2,3]}'
```

--------------------------------

### Send download backup email with PUT /admin/backups/{filename}

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/backups.md

Sends an email containing a download link for the specified backup file.

```bash
curl -X PUT "https://discourse.example.com/admin/backups/2024-01-01-000000-v20240101000000.tar.gz" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system"
```

--------------------------------

### GET /topics/private-messages-sent/{username}.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/private-messages.md

Get a list of private messages sent for a user. This endpoint returns the user's sent private messages folder with a topic_list envelope and sidecar arrays.

```APIDOC
## GET /topics/private-messages-sent/{username}.json

### Description
Get a list of private messages sent for a user.

### Method
GET

### Endpoint
/topics/private-messages-sent/{username}.json

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user whose sent private messages to retrieve.

### Response
#### Success Response (200)
- **users** (array<object>) - Optional - List of users. Each user item includes id (number), username (string), avatar_template (string) - all required.
- **primary_groups** (array) - Optional - List of primary groups.
- **topic_list** (object) - Optional - The topic list envelope.

The topic_list envelope contains fields: can_create_topic (boolean), draft (object), draft_key (string), draft_sequence (number), per_page (number), topics (array). Each topic item includes fields such as id, title, fancy_title, slug, posts_count, reply_count, highest_post_number, created_at, last_posted_at, bumped, bumped_at, unseen, last_read_post_number, unread, new_posts, pinned, visible, closed, archived.

#### Response Example
```json
{
  "users": [
    {
      "id": 1,
      "username": "sam",
      "avatar_template": "https://example.com/avatar.png"
    }
  ],
  "primary_groups": [],
  "topic_list": {
    "can_create_topic": true,
    "draft": {},
    "draft_key": "",
    "draft_sequence": 0,
    "per_page": 30,
    "topics": []
  }
}
```

### Example
```bash
curl -X GET "https://discourse.example.com/topics/private-messages-sent/sam.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" | jq '.users[0].username'
```
```

--------------------------------

### CLI argument handling (toschema.js:6-13)

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/api-reference/toschema.js.md

Checks if both input and output file arguments are provided. If not, prints usage instructions and exits without error.

```javascript
if (process.argv.length > 3) {
  inputFile = process.argv[2];
  outputFile = process.argv[3];
} else {
  console.log('Please specify input and output files!');
  console.log('node schema.js input.json output.yml');
}
```

--------------------------------

### GET /t/{id}.json — Get a single topic

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/topics.md

Retrieves a single topic by its ID. The response contains the topic object with detailed information such as the post stream, metadata, and suggested topics.

```APIDOC
## GET /t/{id}.json

### Description
Retrieves a single topic by its numeric ID, returning the topic object with post stream and metadata.

### Method
GET

### Endpoint
/t/{id}.json

### Parameters
#### Path Parameters
- **id** (string) - Required - The numeric ID of the topic to retrieve.

### Response
#### Success Response (200)
The response is a topic object with the following fields:
- **post_stream** (object) - Required - Contains the posts in the topic.
- **timeline_lookup** (array) - Required - Timeline lookup data.
- **suggested_topics** (array<object>) - Required - Suggested topics list.
- **tags** (array<object>) - Required - Tags associated with the topic.
- **tags_descriptions** (object) - Required - Descriptions for tags.
- **id** (integer) - Required - Topic ID.
- **title** (string) - Required - Topic title.
- **fancy_title** (string) - Required - Formatted title.
- **posts_count** (integer) - Required - Number of posts in the topic.
- **created_at** (string) - Required - Creation timestamp.
- **views** (integer) - Required - View count.
- **reply_count** (integer) - Required - Reply count.
- **like_count** (integer) - Required - Like count.
- **last_posted_at** (string|null) - Required - Last posted timestamp.
- **visible** (boolean) - Required - Whether the topic is visible.
- **closed** (boolean) - Required - Whether the topic is closed.
- **archived** (boolean) - Required - Whether the topic is archived.
- **has_summary** (boolean) - Required - Whether the topic has a summary.
- **slug** (string) - Required - URL slug.
- **word_count** (integer|null) - Required - Word count if available.
- **user_id** (integer) - Required - ID of the topic creator.
- **pinned_globally** (boolean) - Required - Whether pinned globally.
- **pinned_until** (string|null) - Required - Pin expiration.
- **slow_mode_seconds** (integer) - Required - Slow mode duration.
- **draft_key** (string) - Required - Draft key.
- **unpinned** (string|null) - Required - Unpinned status.
- **pinned** (boolean) - Required - Whether pinned.
- **current_post_number** (integer) - Optional - Current post number.
- **highest_post_number** (integer|null) - Required - Highest post number.
- **deleted_by** (string|null) - Required - Deleter info.
- **has_deleted** (boolean) - Required - Whether has deleted posts.
- **actions_summary** (array<object>) - Required - Summary of actions.
- **chunk_size** (integer) - Required - Chunk size.
- **bookmarked** (boolean) - Required - Whether bookmarked.
- **bookmarks** (array) - Required - Bookmarks list.
- **topic_timer** (string|null) - Required - Topic timer info.
- **message_bus_last_id** (integer) - Required - Message bus last ID.
- **participant_count** (integer) - Required - Number of participants.
- **show_read_indicator** (boolean) - Required - Whether show read indicator.
- **thumbnails** (string|null) - Required - Thumbnails info.
- **slow_mode_enabled_until** (string|null) - Required - Slow mode end time.
- **details** (object) - Required - Detailed information.
- **archetype** (string) - Required - Topic archetype.
- **category_id** (integer) - Required - Category ID.
- **deleted_at** (string|null) - Required - Deletion timestamp.
- **featured_link** (string|null) - Required - Featured link.
- **pinned_at** (string|null) - Required - Pin timestamp.
- **image_url** (string|null) - Required - Image URL.
- **draft** (string|null) - Required - Draft content.
- **draft_sequence** (integer) - Required - Draft sequence number.

#### Response Example
An example response using curl:

```bash
curl -X GET "https://discourse.example.com/t/42.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" | jq '.title, .posts_count'
```
```

--------------------------------

### curl GET /tag/{name}.json — Get a specific tag

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/tags.md

Retrieve details for a tag by its name provided in the path. Response includes users, primary_groups, and a topic_list with the same envelope as /latest.json-family endpoints.

```bash
curl -X GET "https://discourse.example.com/tag/design.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system"
```

--------------------------------

### Create backup with POST /admin/backups.json

Source: https://github.com/discourse/discourse_api_docs/blob/main/_autodocs/endpoints/backups.md

Triggers the creation of a new backup. The request body must include the with_uploads boolean parameter.

```bash
curl -X POST "https://discourse.example.com/admin/backups.json" \
  -H "Api-Key: YOUR_API_KEY" -H "Api-Username: system" -H "Content-Type: application/json" \
  -d '{"with_uploads": true}'
```

--------------------------------

### Verify JSON conversion with server

Source: https://github.com/discourse/discourse_api_docs/blob/main/README.md

Load the json file directly instead of live converting the yml file to json. Verify changes still look okay at http://localhost:3001.

```bash
node server.js json
```