Exposing a headless API into game will be very valuable to the Rojo ecosystem. Users can make companion plugins, and we can even utilize it ourselves for one-time plugin injections for rojo open. See issues #321 and #305.
Those are use cases and requests, and we've established there is demand and utility. Now, this issue is attempting to flesh out an execution of this idea. This is an ongoing discussion, not set in stone. Tell us about your use cases and desires so we can make this as valuable as possible!

Proposed interface:

ModuleScript game.Rojo

Plugins and command bar all share the same module cache which allows us to put our interface into a ModuleScript that can be accessed by any plugin. Using the key "Rojo" is easy to remember and follows branding.

Functions

Rojo.API:RequestAccess(plugin: Plugin, apis: {string}): {[string]: boolean}

In order to use any of the Rojo APIs, you must first explicitly request them with this function. Users will be prompted to allow/deny each API, (this function will yield until the user responds) and then the function will return a dictionary where the keys are the requested APIs and the values are booleans which represent the access status (whether or not access was granted). The first argument must be your plugin object for security and reliability purposes, and the second argument is a list of APIs you're requesting access to.

In order to keep our users safe from malicious plugins, RequestAccess must be the first function your plugin calls when using the Rojo API. Attempting to use an API without requesting it beforehand will throw an error. The only exceptions to this are Rojo.API.Version and Rojo.API.ProtocolVersion, since those are useful in checking compatibility before anything else is done.

Example Plugin:

local granted = Rojo.API:RequestAccess(plugin, { "Connected", "ConnectAsync" })
--[[
granted = {
	Connected = true, -- User granted access
	ConnectAsync = false, -- User denied access
}
--]]

Rojo.API:ConnectAsync(host: string?, port: string?): void

Attempts to connect Rojo to the given host and port. Same behavior as the user clicking the Connect button (sync locking, etc., all behave the same).

Rojo.API:DisconnectAsync(): void

Attempts to disconnect any active sync session.

Rojo.API:GetSetting(setting: string): any

Returns the value of the given setting.

Rojo.API:SetSetting(setting: string, value: any): void

Sets the value of the given setting.

function Rojo.API:Notify(msg: string, timeout: number?, actions: { [string]: {text: string, style: string, layoutOrder: number, onClick: (any) -> ()} }?): () -> ()

Sends a Rojo notification that indicates it comes from a third-party plugin. Returns a function that dismisses the notification.

Rojo.API:GetHostAndPort(): (string, string)

Returns the user's chosen host and port.

Rojo.API:CreateApiContext(baseUrl: string): ApiContext

Returns a new ApiContext using the given baseUrl.

Properties (All read-only)

Rojo.API.Version: {number}

The Rojo plugin version. (Example: {7, 2, 1})

Rojo.API.ProtocolVersion: number

The Rojo plugin's protocol version.

Rojo.API.Connected: boolean

Whether Rojo is currently connected to a serve session.

Rojo.API.Address: string?

When Rojo.API.Connected is true, this contains the address of the connected session.

Rojo.API.ProjectName: string?

When Rojo.API.Connected is true, this contains the project name of the connected session.

Events

Rojo.API.Changed: RbxScriptSignal (changedProperty: string, newValue: any?, oldValue: any?)

Fires when any property changes. Passes the name of the changed property and its new and old values.

Considering Please Discuss!

Rojo.InstanceMap

I am considering exposing the InstanceMap- the map of IDs to Instances. I don't know of any use cases though, it is only theoretically useful and feels potentially valuable. However, it's likely a decent chunk of work to do it safely (don't want third party plugins breaking things!) so unless there's a solid use case, it's not planned for this initial API.