Grapevine

https://grapevine.haus/docs
Admin
Grapevine is a cross-game communication network and platform that connects text-based multiplayer...
Tokens:17,593
Snippets:118
Trust Score:8.1
Update:1 day ago
Show doc for...
Tokens:
Raw
### GET /users/me

Source: https://grapevine.haus/docs

Fetch information about the authenticated user using an access token.

```APIDOC
## [GET] /users/me

### Description
Fetch information about the authenticated user using an access token.

### Method
GET

### Endpoint
https://grapevine.haus/users/me

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token.
- **Accept** (string) - Required - application/json.

### Request Example
GET https://grapevine.haus/users/me
Authorization: Bearer my-token
Accept: application/json

### Response
#### Success Response (200)
Returns user information.

#### Response Example
{
  "uid": "their UID",
  "username": "their username",
  "email": "their email"
}
```

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

### Authorization Request URL

Source: https://grapevine.haus/docs

Sample GET request to the authorize endpoint. Requires client_id, scope, state, redirect_uri, and response_type=code. The redirect_uri must be https or localhost.

```http
https://grapevine.haus/oauth/authorize?client_id=YOUR-CLIENT-ID
&scope=profile
&state=STATE
&redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fgrapevine%2Fcallback
&response_type=code
```

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

### web connection object

Source: https://grapevine.haus/docs

Connection object for a web-based game. 'type' is set to "web" and 'url' is the web page to start playing.

```json
{
  "type": "web",
  "url": "https://example.com/play"
}
```

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

### players/sign-in confirmation response

Source: https://grapevine.haus/docs

If a 'ref' is included in the sign-in message, you will get a response back confirming your message.

```json
{
  "event": "players/sign-in",
  "ref": "0e11c053-65b3-477c-aae9-5cd8cf21dc8f"
}
```

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

### Fetch User Information Request and Response

Source: https://grapevine.haus/docs

GET request to /users/me with the access token as a Bearer token in the Authorization header. Returns user information including uid, username, and email.

```http
GET https://grapevine.haus/users/me
Authorization: Bearer my-token
Accept: application/json

200 OK
{
  "uid": "their UID",
  "username": "their username",
  "email": "their email"
}
```

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

### telnet connection object

Source: https://grapevine.haus/docs

Connection object for a standard telnet connection. Note: the source example is missing a comma after the host line.

```json
{
  "type": "telnet",
  "host": "example.com"
  "port": 4000
}
```

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

### authenticate

Source: https://grapevine.haus/docs

Authenticate the WebSocket connection to Grapevine. After successful authentication, you will start receiving broadcasts.

```APIDOC
## authenticate

### Description
Authenticate the WebSocket connection to Grapevine. After successful authentication, you will start receiving broadcasts.

### Event
`authenticate`

### Payload
- `client_id` (string) - Required - Your client ID.
- `client_secret` (string) - Required - Your client secret.
- `supports` (array of strings) - Required - Array of features the connecting game supports. Must contain at least `channels`. Extra unknown options will result in the socket being disconnected.
- `channels` (array of strings) - Optional - Array of channels to subscribe to on start.
- `user_agent` (string) - Optional - Suggested. User agent string for your game.
- `version` (string) - Optional - Suggested. Highest version number your client knows. Defaults to `1.0.0` if not present.

### Request Example
{
  "event": "authenticate",
  "payload": {
    "client_id": "client id",
    "client_secret": "client secret",
    "supports": ["channels"],
    "channels": ["grapevine"],
    "version": "1.0.0",
    "user_agent": "ExVenture 0.23.0"
  }
}

### Response
#### Success Response
- `event` (string) - `authenticate`
- `status` (string) - `success`
- `payload.unicode` (string) - Present to ensure you properly parse unicode characters.
- `payload.version` (string) - Current version of Grapevine.

#### Response Example
{
  "event": "authenticate",
  "status": "success",
  "payload": {
    "unicode": "✔️",
    "version": "2.3.0"
  }
}
```

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

### GMCP Gauge Example Message

Source: https://grapevine.haus/docs

Example GMCP message for a gauge. The message must contain both the value and max value fields for the gauge to update.

```json
Char.Vitals {
  "hp": 10,
  "maxhp": 15,
  "sp": 12,
  "maxsp": 17
}
```

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

### GET /oauth/authorize

Source: https://grapevine.haus/docs

Authorize a user by redirecting them to this endpoint with the required parameters. The response_type must be 'code'.

```APIDOC
## [GET] /oauth/authorize

### Description
Authorize a user by redirecting them to this endpoint with the required parameters. The response_type must be 'code'.

### Method
GET

### Endpoint
https://grapevine.haus/oauth/authorize

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Your client ID.
- **scope** (string) - Required - The scopes you wish to request (e.g., profile, email).
- **state** (string) - Required - A state value to keep track of the request.
- **redirect_uri** (string) - Required - The redirect URI (must be https or localhost).
- **response_type** (string) - Required - Must be 'code'.

### Request Example
https://grapevine.haus/oauth/authorize?client_id=YOUR-CLIENT-ID&scope=profile&state=STATE&redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fgrapevine%2Fcallback&response_type=code

### Response
#### Success Response (302)
Redirects to the redirect_uri with a code parameter.

#### Response Example
Redirect to: https://example.com/auth/grapevine/callback?code=AUTHORIZATION_CODE
```

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

### secure telnet connection object

Source: https://grapevine.haus/docs

Connection object for a TLS secured telnet connection. Note: the source example is missing a comma after the host line.

```json
{
  "type": "secure telnet",
  "host": "example.com"
  "port": 4000
}
```

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

### players/sign-out confirmation response

Source: https://grapevine.haus/docs

If a 'ref' is included in the sign-out message, you will get a response back confirming your message.

```json
{
  "event": "players/sign-out",
  "ref": "da4c5503-dd15-490a-9d0d-85e2c50b72de"
}
```

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

### authenticate event request

Source: https://grapevine.haus/docs

Send this JSON message to authenticate your connection. The 'supports' field is required and must contain at least 'channels'. Extra unknown options will result in disconnection.

```json
{
  "event": "authenticate",
  "payload": {
    "client_id": "client id",
    "client_secret": "client secret",
    "supports": ["channels"],
    "channels": ["grapevine"],
    "version": "1.0.0",
    "user_agent": "ExVenture 0.23.0"
  }
}
```

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

### channels/broadcast event

Source: https://grapevine.haus/docs

Broadcast event received when a subscribed channel gets a new message.

```json
{
  "event": "channels/broadcast",
  "ref": "89036074-446f-41ab-b87a-44ef1f962f2e",
  "payload": {
    "channel": "grapevine",
    "message": "Hello everyone!",
    "game": "ExVenture",
    "name": "Player"
  }
}
```

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

### achievements/create

Source: https://grapevine.haus/docs

Creates a new achievement with the provided attributes. Returns the created achievement with its key and full attributes.

```APIDOC
## achievements/create

### Description
Creates a new achievement with the provided attributes. Returns the created achievement with its key and full attributes.

### Event
achievements/create

### Parameters
- `ref` (string) - Required - A unique reference for the request.
- `payload` (object) - Required - Achievement attributes to set.
  - `title` (string) - Required - Achievement title.
  - `points` (integer) - Required - Points awarded.
  - `description` (string) - Optional - Achievement description.
  - `display` (boolean) - Optional - If false, the achievement is blurred until unlocked.
  - `partial_progress` (boolean) - Optional - If true, `total_progress` must be provided.
  - `total_progress` (integer) - Optional - Total progress required.

### Request Example
{
  "event": "achievements/create",
  "ref": "1dfae6f6-c0a8-4da5-a1e3-3ba656880d90",
  "payload": {
    "title": "Level Up!",
    "points": 10
  }
}

### Response
#### Success Response
- `key` (string) - Read-only ID of the created achievement.
- `title` (string) - Achievement title.
- `description` (string) - Achievement description.
- `points` (integer) - Points awarded.
- `display` (boolean) - If false, the achievement is blurred until unlocked.
- `partial_progress` (boolean) - If true, `total_progress` must be provided.
- `total_progress` (integer) - Total progress required.

#### Response Example
{
  "event": "achievements/create",
  "ref": "1dfae6f6-c0a8-4da5-a1e3-3ba656880d90",
  "status": "success",
  "payload": {
    "key": "ea7fb436-a99e-4e78-ad10-46acc6fb6912",
    "title": "Level Up!",
    "description": "You leveled up to level 10!",
    "points": 10,
    "display": true,
    "partial_progress": false,
    "total_progress": null
  }
}

#### Error Response
- `errors` (object) - Map of field names to arrays of error messages.

#### Error Example
{
  "event": "achievements/update",
  "ref": "1dfae6f6-c0a8-4da5-a1e3-3ba656880d90",
  "status": "failure",
  "payload": {
    "errors": {
      "title": ["can't be blank"]
    }
  }
}
```

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

### players/sign-in event message

Source: https://grapevine.haus/docs

Send this message when a player signs into your game. The 'ref' is optional, 'name' is required. You will not receive a 'players/sign-in' event back for messages you send.

```json
{
  "event": "players/sign-in",
  "ref": "0e11c053-65b3-477c-aae9-5cd8cf21dc8f",
  "payload": {
    "name": "Player"
  }
}
```

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

### restart event

Source: https://grapevine.haus/docs

Sent before a server restart due to a deploy. The connection may drop at any moment after receiving this event. The 'downtime' field is a suggested wait time in seconds.

```json
{
  "event": "restart",
  "ref": "f15ed228-ad43-4af4-9466-7d353fc9bf11",
  "payload": {
    "downtime": 15
  }
}
```

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

### achievements/sync request

Source: https://grapevine.haus/docs

Request to sync achievements. Requires a 'ref' field.

```json
{
  "event": "achievements/sync",
  "ref": "1dfae6f6-c0a8-4da5-a1e3-3ba656880d90"
}
```

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

### players/status request

Source: https://grapevine.haus/docs

Send this event to check the status of other players on the network. The 'ref' is required.

```json
{
  "event": "players/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4"
}
```

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

### games/connect

Source: https://grapevine.haus/docs

Event received when another game connects to the network. Use it to notify local players that a game has come online.

```APIDOC
## games/connect

### Description
Received while connected with the `games` flag. Indicates that another game has come online from the network.

### Event
`games/connect`

### Payload
- **game** (string) - Required - The name of the game that connected.

### Example
```json
{
  "event": "games/connect",
  "payload": {
    "game": "ExVenture"
  }
}
```
```

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

### WebSocket Connect

Source: https://grapevine.haus/docs

Connect to the Grapevine network by pointing your WebSocket client to the provided URL.

```APIDOC
## WebSocket Connect

### Description
Connect to the Grapevine network by pointing your WebSocket client to the provided URL.

### Endpoint
wss://grapevine.haus/socket

### Notes
- After connecting, you must send an `authenticate` message to authenticate your connection.
- The connection may drop at any time; your game should handle reconnection gracefully.
- You must support UTF-8 at the server level.

### Error Codes
- 4000: Authentication failed
- 4001: Heartbeat failure
```

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

### channels/subscribe

Source: https://grapevine.haus/docs

Subscribe to a new channel on your currently connected socket. The channel name is required and validated; a ref is optional for confirmation.

```APIDOC
## channels/subscribe

### Description
Subscribe to a new channel on your currently connected socket.

### Event
channels/subscribe

### Payload
- `channel` (string) - Required - The channel name to subscribe to.

### Optional Fields
- `ref` (string) - Optional - A client-generated reference for message correlation.

### Request Example
{
  "event": "channels/subscribe",
  "ref": "a6f8006d-ddac-465e-a3df-fb440e83189b",
  "payload": {
    "channel": "grapevine"
  }
}

### Response
If a `ref` is included, a confirmation response is sent.

#### Success Response Example
{
  "event": "channels/subscribe",
  "ref": "a6f8006d-ddac-465e-a3df-fb440e83189b"
}

#### Failure Response Example
{
  "event": "channels/subscribe",
  "ref": "a6f8006d-ddac-465e-a3df-fb440e83189b",
  "status": "failure",
  "error": "Could not subscribe to 'bad channel name'"
}
```

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

### players/sign-in

Source: https://grapevine.haus/docs

Sends a message when a player signs into your game. It broadcasts to other games and updates Grapevine's tracking. Optionally include a ref to receive a confirmation response.

```APIDOC
## players/sign-in

### Description
Sends a message when a player signs into your game. It broadcasts to other games and updates Grapevine's tracking of who is signed in. You will not receive a players/sign-in event back for messages you send.

### Event
`players/sign-in`

### Parameters
#### Payload
- `name` (string) - Required - The player's name.
- `ref` (string) - Optional - A reference identifier for the message.

### Request Example
{
  "event": "players/sign-in",
  "ref": "0e11c053-65b3-477c-aae9-5cd8cf21dc8f",
  "payload": {
    "name": "Player"
  }
}

### Response
If a `ref` is included, you will receive a confirmation response.

#### Response Example
{
  "event": "players/sign-in",
  "ref": "0e11c053-65b3-477c-aae9-5cd8cf21dc8f"
}

### Received Update
While connected with the `players` flag, you may receive an update from another game.

#### Received Update Example
{
  "event": "players/sign-in",
  "payload": {
    "game": "ExVenture",
    "name": "Player"
  }
}

```

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

### heartbeat event from server

Source: https://grapevine.haus/docs

Sent by the server after authentication. You must respond with your own heartbeat event.

```json
{
  "event": "heartbeat",
}
```

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

### games/status

Source: https://grapevine.haus/docs

Send this event to check the status of other games on the network. You can query all games or a single game by name. The response contains a message per connected game or an error if the game is unknown.

```APIDOC
## games/status

### Description
Send a `games/status` event to check the status of other games on the network. You can query all games or a single game by name. The response contains a message per connected game or an error if the game is unknown.

### Event
`games/status`

### Parameters
#### Request Payload
- **ref** (string) - Required - A unique reference for the request.
- **game** (string) - Optional - The name of a specific game to query. If omitted, all connected games are returned.

### Request Example (All Games)
```json
{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4"
}
```

### Request Example (Single Game)
```json
{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "payload": {
    "game": "ExVenture"
  }
}
```

### Response
#### Success Response
- **event** (string) - The event name, `games/status`.
- **ref** (string) - The reference from the request.
- **status** (string) - `success`.
- **payload** (object) - Contains game information.
  - **game** (string) - The name of the game.
  - **display_name** (string) - A less restrictive name for the game.
  - **description** (string) - Text about the game.
  - **homepage_url** (string) - The home page for the game.
  - **user_agent** (string) - The reported user agent of the connecting game. May not be present.
  - **user_agent_repo_url** (string) - Source code repository for the user agent. May not be present.
  - **connections** (array) - Array of connection objects. May not be present.
  - **supports** (array) - Array of what the socket supports. May not be present.
  - **channels** (array) - Array of channels the game is listening to. May not be present.
  - **players_online_count** (number) - Number of players online. May not be present.

#### Response Example
```json
{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "status": "success",
  "payload": {
    "game": "ExVenture",
    "display_name": "An ExVenture game",
    "description": "...",
    "homepage_url": "https://...",
    "user_agent": "ExVenture 0.26.0",
    "user_agent_repo_url": "https://...",
    "connections": [
      {"type": "telnet", "host": "example.com", "port": 4000},
      {"type": "web", "url": "https://example.com/play"}
    ],
    "supports": ["channels", "players", "tells", "games"],
    "channels": ["gossip"],
    "players_online_count": 3
  }
}
```

#### Error Response
- **event** (string) - The event name, `games/status`.
- **ref** (string) - The reference from the request.
- **status** (string) - `failure`.
- **error** (string) - Error message, e.g., `unknown game`.

#### Error Example
```json
{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "status": "failure",
  "error": "unknown game"
}
```

### Connection Object
A connection object contains ways of connecting to play the game. Current connection types are: `web`, `telnet`, and `secure telnet`.

#### web
- **type** (string) - Set to `web`.
- **url** (string) - A web page to start playing the game.

Example:
```json
{
  "type": "web",
  "url": "https://example.com/play"
}
```

#### telnet
- **type** (string) - Set to `telnet`.
- **host** (string) - The host name to connect to.
- **port** (number) - The port to connect to.

Example:
```json
{
  "type": "telnet",
  "host": "example.com",
  "port": 4000
}
```

#### secure telnet
- **type** (string) - Set to `secure telnet`.
- **host** (string) - The host name to connect to.
- **port** (number) - The port to connect to.

Example:
```json
{
  "type": "secure telnet",
  "host": "example.com",
  "port": 4000
}
```
```

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

### achievements/sync

Source: https://grapevine.haus/docs

Requests a series of events that send all achievements the connecting game has. Each event contains at most 10 achievements and includes the total count.

```APIDOC
## achievements/sync

### Description
Requests a series of events that send all of the achievements that the connecting game has. Each event contains at most 10 achievements and includes the total count.

### Event
achievements/sync

### Parameters
- `ref` (string) - Required - A unique reference for the request.

### Request Example
{
  "event": "achievements/sync",
  "ref": "1dfae6f6-c0a8-4da5-a1e3-3ba656880d90"
}

### Response
#### Success Response
- `total` (integer) - Total number of achievements.
- `achievements` (array) - Array of achievement objects.

#### Achievement Attributes
- `key` (string) - Read-only ID used in other events.
- `title` (string) - Achievement title.
- `description` (string) - Achievement description.
- `points` (integer) - Points awarded.
- `display` (boolean) - If false, the achievement is blurred until unlocked.
- `partial_progress` (boolean) - If true, `total_progress` must be provided.
- `total_progress` (integer) - Total progress required.

#### Response Example
{
  "event": "achievements/sync",
  "ref": "1dfae6f6-c0a8-4da5-a1e3-3ba656880d90",
  "payload": {
    "total": 15,
    "achievements": [
      {
        "key": "ea7fb436-a99e-4e78-ad10-46acc6fb6912",
        "title": "Level Up!",
        "description": "You leveled up to level 10!",
        "points": 10,
        "display": true,
        "partial_progress": false,
        "total_progress": null
      }
    ]
  }
}
```

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

### achievements/create success response

Source: https://grapevine.haus/docs

Success response containing the created achievement's key and full attributes.

```json
{
  "event": "achievements/create",
  "ref": "1dfae6f6-c0a8-4da5-a1e3-3ba656880d90",
  "status": "success",
  "payload": {
    "key": "ea7fb436-a99e-4e78-ad10-46acc6fb6912",
    "title": "Level Up!",
    "description": "You leveled up to level 10!",
    "points": 10,
    "display": true,
    "partial_progress": false,
    "total_progress": null,
  }
}
```

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

### channels/subscribe request

Source: https://grapevine.haus/docs

Subscribe to a channel. The `ref` is optional; if included, a response will be returned. The `channel` field is required.

```json
{
  "event": "channels/subscribe",
  "ref": "a6f8006d-ddac-465e-a3df-fb440e83189b",
  "payload": {
    "channel": "grapevine"
  }
}
```

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

### achievements/create request

Source: https://grapevine.haus/docs

Request to create a new achievement. Requires a 'ref' field and payload with achievement attributes.

```json
{
  "event": "achievements/create",
  "ref": "1dfae6f6-c0a8-4da5-a1e3-3ba656880d90"
  "payload": {
    "title": "Level Up!",
    "points": 10
  }
}
```

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

### players/sign-in update from another game

Source: https://grapevine.haus/docs

While connected with the 'players' flag, you may receive an update from another game when a player signs in. You may wish to broadcast to your local players that someone has come online.

```json
{
  "event": "players/sign-in",
  "payload": {
    "game": "ExVenture",
    "name": "Player"
  }
}
```

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

### channels/subscribe response

Source: https://grapevine.haus/docs

Response confirming a subscription when a `ref` is included.

```json
{
  "event": "channels/subscribe",
  "ref": "a6f8006d-ddac-465e-a3df-fb440e83189b"
}
```

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

### achievements/sync response

Source: https://grapevine.haus/docs

Response containing a batch of achievements. Each event contains at most 10 achievements and the total count.

```json
{
  "event": "achievements/sync",
  "ref": "1dfae6f6-c0a8-4da5-a1e3-3ba656880d90",
  "payload": {
    "total": 15,
    "achievements": [
      {
        "key": "ea7fb436-a99e-4e78-ad10-46acc6fb6912",
        "title": "Level Up!",
        "description": "You leveled up to level 10!",
        "points": 10,
        "display": true,
        "partial_progress": false,
        "total_progress": null,
      }
    ]
  }
}
```

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

### POST /oauth/token

Source: https://grapevine.haus/docs

Exchange an authorization code for an access token. Access tokens expire after 1 hour.

```APIDOC
## [POST] /oauth/token

### Description
Exchange an authorization code for an access token. Access tokens expire after 1 hour.

### Method
POST

### Endpoint
https://grapevine.haus/oauth/token

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Your client ID.
- **code** (string) - Required - The authorization code received from the authorize step.
- **grant_type** (string) - Required - Must be 'authorization_code'.
- **redirect_uri** (string) - Required - The redirect URI used in the authorization request.

### Request Example
POST https://grapevine.haus/oauth/token?client_id=YOUR-CLIENT-ID&code=CODE&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fgrapevine%2Fcallback

### Response
#### Success Response (200)
Returns an access token.

#### Response Example
{
  "access_token": "my-token",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

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

### games/status error response

Source: https://grapevine.haus/docs

Received when requesting a single game that is unknown. Contains status 'failure' and an error message.

```json
{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "status": "failure",
  "error": "unknown game"
}
```

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

### tells/send event payload

Source: https://grapevine.haus/docs

JSON payload for sending a tell via the tells/send event. Requires ref, from_name, to_game, to_name, sent_at (ISO8601 UTC with Z), and message.

```json
{
  "event": "tells/send",
  "ref": "5c528fc3-cb9e-4867-98ea-6e235594241e",
  "payload": {
    "from_name": "Player",
    "to_game": "ExVenture",
    "to_name": "eric",
    "sent_at": "2018-07-17T13:12:28Z",
    "message": "hi"
  }
}
```

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

### games/status request payload

Source: https://grapevine.haus/docs

Send to check the status of all connected games. The 'ref' field is required.

```json
{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4"
}
```

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

### channels/send

Source: https://grapevine.haus/docs

Send a new message to a channel you are subscribed to. The message will have MXP tags stripped before broadcasting; do not send MXP data.

```APIDOC
## channels/send

### Description
To send a new message, use this event. The `message` in the payload will have MXP tags stripped before broadcasting. Do not send MXP data. You will not get a `channels/broadcast` event for messages you send.

### Event
channels/send

### Payload
- `channel` (string) - Required - The channel to send to. Must be a channel you are subscribed to.
- `name` (string) - Required - The sender's name.
- `message` (string) - Required - The message content.

### Optional Fields
- `ref` (string) - Optional - A client-generated reference for message correlation.

### Request Example
{
  "event": "channels/send",
  "ref": "28523394-6dcf-4c2a-ad1d-2d0ef8bb823b",
  "payload": {
    "channel": "grapevine",
    "name": "Player",
    "message": "Hello everyone!"
  }
}

### Response
If a `ref` is included, a confirmation response is sent.

#### Success Response Example
{
  "event": "channels/send",
  "ref": "28523394-6dcf-4c2a-ad1d-2d0ef8bb823b"
}
```

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

### channels/broadcast

Source: https://grapevine.haus/docs

This event is received when a channel you are subscribed to receives a new message. It is not sent by the client but is documented for reference.

```APIDOC
## channels/broadcast

### Description
When a channel you are subscribed to receives a new message you will get a broadcast.

### Event
channels/broadcast

### Payload
- `channel` (string) - Required - The channel name.
- `message` (string) - Required - The message content.
- `game` (string) - Optional - The game identifier (see Common Vocabulary).
- `name` (string) - Optional - The sender's name (see Common Vocabulary).

### Example
{
  "event": "channels/broadcast",
  "ref": "89036074-446f-41ab-b87a-44ef1f962f2e",
  "payload": {
    "channel": "grapevine",
    "message": "Hello everyone!",
    "game": "ExVenture",
    "name": "Player"
  }
}
```

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

### channels/send response

Source: https://grapevine.haus/docs

Response confirming a sent message when a `ref` is included.

```json
{
  "event": "channels/send",
  "ref": "28523394-6dcf-4c2a-ad1d-2d0ef8bb823b",
}
```

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

### channels/unsubscribe response

Source: https://grapevine.haus/docs

Response confirming an unsubscription when a `ref` is included.

```json
{
  "event": "channels/unsubscribe",
  "ref": "e4d07334-4a4b-44ba-94dc-2b937160a466"
}
```

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

### channels/send request

Source: https://grapevine.haus/docs

Send a new message to a channel. The `ref` is optional; if included, a response will be returned. The `channel`, `name`, and `message` fields are required. MXP tags are stripped from the message before broadcasting.

```json
{
  "event": "channels/send",
  "ref": "28523394-6dcf-4c2a-ad1d-2d0ef8bb823b",
  "payload": {
    "channel": "grapevine",
    "name": "Player",
    "message": "Hello everyone!"
  }
}
```

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

### games/status single game update request

Source: https://grapevine.haus/docs

You can request an update to a single game by adding its name in the payload. The 'ref' is required, and 'name' is required. You will only receive an update for that game.

```json
{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "payload": {
    "game": "ExVenture"
  }
}
```

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

### achievements/update success response

Source: https://grapevine.haus/docs

Success response containing the updated achievement's key and full attributes.

```json
{
  "event": "achievements/update",
  "ref": "1dfae6f6-c0a8-4da5-a1e3-3ba656880d90",
  "status": "success",
  "payload": {
    "key": "ea7fb436-a99e-4e78-ad10-46acc6fb6912",
    "title": "Leveled Up!",
    "description": "You leveled up to level 10!",
    "points": 15,
    "display": true,
    "partial_progress": false,
    "total_progress": null,
  }
}
```

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

### channels/unsubscribe request

Source: https://grapevine.haus/docs

Unsubscribe from a channel. The `ref` is optional; if included, a response will be returned. The `channel` field is required.

```json
{
  "event": "channels/unsubscribe",
  "ref": "e4d07334-4a4b-44ba-94dc-2b937160a466",
  "payload": {
    "channel": "grapevine"
  }
}
```

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

### heartbeat

Source: https://grapevine.haus/docs

Server sends heartbeat events after authentication. You must respond with your own heartbeat to keep the connection alive.

```APIDOC
## heartbeat

### Description
Server sends heartbeat events after authentication. You must respond with your own heartbeat to keep the connection alive.

### Event
`heartbeat`

### Request (from server)
{
  "event": "heartbeat"
}

### Response (from client)
- `event` (string) - `heartbeat`
- `payload.players` (array of strings) - Optional but suggested. Full player list to keep Grapevine in sync.

### Response Example
{
  "event": "heartbeat",
  "payload": {
    "players": ["player"]
  }
}

### Notes
- If you do not respond to heartbeats, the socket will be closed after three failed beats.
```

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

### channels/unsubscribe

Source: https://grapevine.haus/docs

Unsubscribe from a channel you are currently subscribed to. The channel name is required; a ref is optional for confirmation.

```APIDOC
## channels/unsubscribe

### Description
Unsubscribe to a channel you are subscribed to.

### Event
channels/unsubscribe

### Payload
- `channel` (string) - Required - The channel name to unsubscribe from.

### Optional Fields
- `ref` (string) - Optional - A client-generated reference for message correlation.

### Request Example
{
  "event": "channels/unsubscribe",
  "ref": "e4d07334-4a4b-44ba-94dc-2b937160a466",
  "payload": {
    "channel": "grapevine"
  }
}

### Response
If a `ref` is included, a confirmation response is sent.

#### Success Response Example
{
  "event": "channels/unsubscribe",
  "ref": "e4d07334-4a4b-44ba-94dc-2b937160a466"
}
```

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

### tells/send success response

Source: https://grapevine.haus/docs

Response received when the tell is successfully sent. Contains the same ref and a status of 'success'.

```json
{
  "event": "tells/send",
  "ref": "5c528fc3-cb9e-4867-98ea-6e235594241e",
  "status": "success"
}
```

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

### players/status response

Source: https://grapevine.haus/docs

In response to a players/status request, you will receive a message per connected game. The 'players' field is the list of players currently online.

```json
{
  "event": "players/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "payload": {
     "game": "ExVenture",
     "players: ["admin"]
  }
}
```

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

### players/sign-out update from another game

Source: https://grapevine.haus/docs

While connected with the 'players' flag, you may receive an update from another game when a player signs out. You may wish to broadcast to your local players that someone has gone offline.

```json
{
  "event": "players/sign-out",
  "payload": {
    "game": "ExVenture",
    "name": "Player"
  }
}
```

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

### achievements/create error response

Source: https://grapevine.haus/docs

Error response when there are validation errors, e.g., title can't be blank.

```json
{
  "event": "achievements/update",
  "ref": "1dfae6f6-c0a8-4da5-a1e3-3ba656880d90",
  "status": "failure",
  "payload": {
    "errors": {
      "title": ["can't be blank"]
    }
  }
}
```

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

### players/sign-out event message

Source: https://grapevine.haus/docs

Send this message when a player signs out of your game. The 'ref' is optional, 'name' is required. You will not receive a 'players/sign-out' event back for messages you send.

```json
{
  "event": "players/sign-out",
  "ref": "da4c5503-dd15-490a-9d0d-85e2c50b72de",
  "payload": {
    "name": "Player"
  }
}
```

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

### tells/send failure response

Source: https://grapevine.haus/docs

Response received when the tell fails to send. Contains a status of 'failure' and an error message. Possible errors include 'game offline', 'sending player offline', 'receiving player offline', and 'not supported'.

```json
{
  "event": "tells/send",
  "ref": "5c528fc3-cb9e-4867-98ea-6e235594241e",
  "status": "failure",
  "error": "game offline"
}
```

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

### players/status

Source: https://grapevine.haus/docs

Requests the status of other players on the network. Requires a ref. Returns a message per connected game with the list of online players.

```APIDOC
## players/status

### Description
To check the status of other players on the network, send a `players/status` event. You will receive a message per connected game.

### Event
`players/status`

### Parameters
#### Payload
- `ref` (string) - Required - A reference identifier for the message.

### Request Example
{
  "event": "players/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4"
}

### Response
You will receive a message per connected game.

#### Response Example
{
  "event": "players/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "payload": {
    "game": "ExVenture",
    "players": ["admin"]
  }
}

### Single Game Update
You can request an update to a single game by adding its name in the payload.

#### Request Example
{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "payload": {
    "game": "ExVenture"
  }
}

#### Response
You will only receive an update for that game. It will look the same as above.

```

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

### Token Generation Request

Source: https://grapevine.haus/docs

POST to the /oauth/token endpoint to exchange the authorization code for an access token. Access tokens expire after 1 hour.

```http
POST https://grapevine.haus/oauth/token?client_id=YOUR-CLIENT-ID
&code=CODE
&grant_type=authorization_code
&redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fgrapevine%2Fcallback
```

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

### tells/send

Source: https://grapevine.haus/docs

Send a tell to a player in another game. Requires the tells support flag. The event payload includes sender, recipient, timestamp, and message. A success or failure response is returned.

```APIDOC
## tells/send

### Description
Send a tell to a player in another game. Requires the tells support flag. The event payload includes sender, recipient, timestamp, and message. A success or failure response is returned.

### Event
`tells/send`

### Payload
- `ref` (string) - Required - Unique reference for the event.
- `from_name` (string) - Required - Name of the player sending the tell.
- `to_game` (string) - Required - Name of the game that will process the tell. The server matches this case-insensitively against connected games.
- `to_name` (string) - Required - Name of the receiving player.
- `sent_at` (string) - Required - ISO8601 formatted timestamp in UTC (use `Z` format).
- `message` (string) - Required - Body of the tell.

### Request Example
{
  "event": "tells/send",
  "ref": "5c528fc3-cb9e-4867-98ea-6e235594241e",
  "payload": {
    "from_name": "Player",
    "to_game": "ExVenture",
    "to_name": "eric",
    "sent_at": "2018-07-17T13:12:28Z",
    "message": "hi"
  }
}

### Response
#### Success Response
- `event` (string) - The event name.
- `ref` (string) - The reference from the request.
- `status` (string) - `success`.

#### Response Example
{
  "event": "tells/send",
  "ref": "5c528fc3-cb9e-4867-98ea-6e235594241e",
  "status": "success"
}

#### Error Response
- `event` (string) - The event name.
- `ref` (string) - The reference from the request.
- `status` (string) - `failure`.
- `error` (string) - One of: `game offline`, `sending player offline`, `receiving player offline`, `not supported`.

#### Error Response Example
{
  "event": "tells/send",
  "ref": "5c528fc3-cb9e-4867-98ea-6e235594241e",
  "status": "failure",
  "error": "game offline"
}
```

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

### restart

Source: https://grapevine.haus/docs

Received when Grapevine knows a restart is imminent. The connection may drop at any moment after this event.

```APIDOC
## restart

### Description
Received when Grapevine knows a restart is imminent. The connection may drop at any moment after this event.

### Event
`restart`

### Payload
- `ref` (string) - Unique reference for the event.
- `payload.downtime` (integer) - Suggested amount of seconds to wait before restarting.

### Request Example
{
  "event": "restart",
  "ref": "f15ed228-ad43-4af4-9466-7d353fc9bf11",
  "payload": {
    "downtime": 15
  }
}
```
Tokens:
Raw