Skip to main content
Documentation Powered by Redocly

GroceryBot API (v2.12.x)

Download OpenAPI specification:Download

Terms of Service

Interact with GroceryBot directly through its API at https://api.grocerybot.net.

GroceryBot's Website

Auth

Unstable — internal use. These endpoints are not covered by public API stability guarantees; request and response shapes may change without a major version bump.

Discord OAuth token exchange, JWT refresh, and session logout.

Exchange Discord OAuth code for GroceryBot tokens

Unstable (internal): Not covered by public API stability guarantees; breaking changes may occur without a major version bump.

Accepts the authorization code, PKCE code_verifier, and redirect_uri from the Discord OAuth flow (client-driven). Validates redirect_uri against the server allowlist, exchanges with Discord, and returns a GroceryBot JWT plus refresh token.

Request Body schema: application/json
code
required
string

Authorization code from Discord OAuth redirect.

code_verifier
required
string

PKCE code verifier (S256) used in the authorization request.

redirect_uri
required
string

Must match the redirect URI used with Discord and must be allowed on the server.

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "code_verifier": "string",
  • "redirect_uri": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "refresh_token": "string",
  • "expires_in": 0
}

Refresh GroceryBot access token

Unstable (internal): Not covered by public API stability guarantees; breaking changes may occur without a major version bump.

Exchanges a valid refresh token for a new access JWT and a rotated refresh token. Returns expires_in for the access token (seconds).

Request Body schema: application/json
refresh_token
required
string

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "refresh_token": "string",
  • "expires_in": 0
}

Log out (revoke session)

Unstable (internal): Not covered by public API stability guarantees; breaking changes may occur without a major version bump.

Deletes the authenticated user's session(s). Requires Authorization: Bearer with the GroceryBot JWT. Does not use X-Guild-ID.

Authorizations:
bearerAuth

Responses

List guilds shared by the user and bot

Returns Discord guilds for the authenticated user that the bot is also in. Requires Authorization: Bearer. Does not use X-Guild-ID.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "guilds": [
    ]
}

GET Grocery Lists and Entries

Get your server's grocery lists and entries. Note: you have to map the relationship between a grocery list and the groceries themselves.

Authorizations:
basicApiClientbearerAuth
header Parameters
X-Guild-ID
required
string

Required for Bearer-authenticated requests to guild-scoped routes (see SPEC-001). Ignored for Basic auth (guild is determined from the API client scope).

Responses

Response samples

Content type
application/json
{
  • "guild_id": "string",
  • "grocery_entries": [
    ],
  • "grocery_lists": [
    ]
}

BATCH DELETE Grocery Entries

Delete multiple grocery entries by primary key IDs in one request (at most 300 IDs). IDs must belong to the guild selected by credentials (X-Guild-ID for Bearer). Duplicate IDs in the request are ignored. If any ID does not exist in this guild, the request fails with 404 and nothing is deleted.

Authorizations:
basicApiClientbearerAuth
header Parameters
X-Guild-ID
required
string

Required for Bearer-authenticated requests to guild-scoped routes (see SPEC-001). Ignored for Basic auth (guild is determined from the API client scope).

Request Body schema: application/json
ids
required
Array of integers [ 1 .. 300 ] items [ items >= 1 ]

Primary keys of grocery entries to delete (see GET /grocery-lists). Values are unsigned (positive integers). At most 300 IDs per request.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

POST Grocery Entry

Create a new grocery entry for your server. To attach it to a grocery list, obtain your server's grocery lists from GET /grocery-lists and put it into grocery_list_id.

Authorizations:
basicApiClientbearerAuth
header Parameters
X-Guild-ID
required
string

Required for Bearer-authenticated requests to guild-scoped routes (see SPEC-001). Ignored for Basic auth (guild is determined from the API client scope).

Request Body schema: application/json

Creates a new grocery entry.

item_desc
required
string

Description of the entry. For example, /gro chicken would result in this field being chicken.

grocery_list_id
integer or null <int64>

The foreign key pointing to a particular grocery list in your server. A null value means that this belongs to the server's default grocery list.

Responses

Request samples

Content type
application/json
{
  • "item_desc": "string",
  • "grocery_list_id": 0
}

DELETE Grocery Entry

Delete a grocery entry by its ID. You can obtain the ID from the GET /grocery-lists endpoint.

Authorizations:
basicApiClientbearerAuth
path Parameters
id
required
integer <int64>

The ID of the grocery entry to delete.

header Parameters
X-Guild-ID
required
string

Required for Bearer-authenticated requests to guild-scoped routes (see SPEC-001). Ignored for Basic auth (guild is determined from the API client scope).

Responses

GET guild registrations

Returns active registrations for the guild selected by credentials (Basic scope) or by X-Guild-ID (Bearer).

Authorizations:
basicApiClientbearerAuth
header Parameters
X-Guild-ID
required
string

Required for Bearer-authenticated requests to guild-scoped routes (see SPEC-001). Ignored for Basic auth (guild is determined from the API client scope).

Responses

Response samples

Content type
application/json
[
  • {
    }
]