NSV Pseudo-API Documentation

Overview

This page may be of interest to you if you are a programmer who works with NationStates and Discord, or if you would like to become one.

In general, an Application Programming Interface (API) allows a script or bot to efficiently access data from a website or other remote server. For example, NationStates has an API that provides information about nations, regions, the WA, etc. Scripts typically interact with APIs by making HTTP requests to API endpoints.

NSVerify is a NS verification and role management system for Discord servers, powered by the AugustinAndroid v2 Discord bot.

NSVerify now provides a "pseudo-API" (pAPI) for public use. Rather than by making HTTP requests to a public server (which in this case does not exist), scripts can interact with this pAPI by sending and receiving messages on Discord.

Usage

1. The user (probably a Discord bot, but could also be a human) sends a message in a channel it shares with AugustinAndroid v2. This message contains a token, an endpoint, and an optional argument. The token, which is needed to match the request with the response, can be any arbitrary string.

2. AugustinAndroid v2 responds with a message containing the same token and the output data.

3. The user reads the message and parses the data.

Syntax

Requests

NSV_API_REQUEST [token] [endpoint] [*argument]

Requests always begin with NSV_API_REQUEST. Tokens can be any string, but if you expect to make pAPI calls at high frequency or in busy channels, it is best to make them unique.

Endpoint	Description	Argument
list_discord_accounts	List the IDs of the server members who have verified the given nation.	A nation name, such as August.
list_nations	List the nations verified by a member.	A member's Discord ID, such as 213088304537534464.
list_nations_with_regions	List the nations verified by a server member, along with the last known region for each nation, if any.	A member's Discord ID, such as 213088304537534464.
users_from_region	List the IDs of the server members with verified nations in the given region, if any.	The name of a region, such as Cape of Good Hope.
users_by_region	List all the regions where server members possess verified nations, and list the IDs of the members living in each region.	None.
list_unverified	List the IDs of the server members with no nations verified in the server.	None.

Responses

NSV_API_RESPONSE [token] [data]

Lists are separated with commas. Names are always lowercase, with underscores instead of spaces. If the output is longer than 2000 characters, it will be contained in a text file. If no data is available (eg, a list_nations request for a member with no verified nations), the output is 0.

Endpoint	Output Format Example
list_discord_accounts	213088304537534464
list_nations	august,mercantana,conch_kingdom
list_nations_with_regions	august|cape_of_good_hope,mercantana|lands_end,conch_kingdom|conch_kingdom
users_from_region	228353948552134658,754524576670548049,213088304537534464,293518673417732098
users_by_region	cape_of_good_hope:213088304537534464,311192853684420618 lands_end:831729061399232574,227107561805971456,279767631932948480 conch_kingdom:228353948552134658,754524576670548049,213088304537534464
list_unverified	853073727231361044,717389894921748573,829456280355209287

Limitations

• The pAPI may only be used on servers, not in private messages. Bots cannot send private messages to other bots anyway, due to Discord limitations.

• NSVerify must be enabled on the server.

• Humans may use the pAPI in the exact same way as bots.

• Users are not subject to any rate limits.

• Users or servers may be blacklisted by the developer, temporarily or permanently, at any time for any reason. pAPI calls are logged and reviewed by the developer.

• The same privacy limits that apply to ordinary bot commands also apply to the pAPI.

  • Only publicly verified nations and nations verified on a particular server will be visible on that server.

  • If viewing privately verified nations is limited to server staff (in NSV Settings), a user will only be able to view another user's privately verified nations if he/she/it has a staff role or the Administrator permission.

Future Additions

If you have a request for more features/endpoints, join the AugustinAndroid v2 support server and post in #suggestions. You can also send me a telegram or a private message at August#4079, but there is a much higher chance I will overlook or forget about your suggestion.