API Endpoints

You can create a free account or log in if you already have one and get your API key.

#   Overview

Our API can be used with following domains:

• api.grand.app (recommended)
• api.usegrand.com (deprecated)

Following endpoints are supported by Grand:

• /generate: To generate open-ended text using our GPT models
• /playbook/use: To use a stored Playbook
• /socket/create: To create a socket connection URL

Please use only https protocol with all the requests.

#   Authentication

We need following headers to be always present in your API requests.

Both of these can be found in your dashboard.

#   /generate

For free-form text generation using GPT models.

URL: api.grand.app/generate

Method: POST

Request Format: JSON body

Response: JSON

E.g. Request body:

{
    "text": "Grand API is simple, easy and",
    "model_id": "Ukg1ClHdlG03aG7cAu8J", // id of GPT-J
    "creativity": 30,
    "stop": ".",
    "max": 50,
    "only_response": true
  }

E.g. Success Response:

{
    "ok": true,
    "id": "47eb786b",
    "data": {
      "text": " fast.",
    }
  }

E.g. Success Response with n: 3:

{
  "ok": true,
  "outputs": [
    {
      "id": "6917294e",
      "data": {
        "text": " effective."
      }
    },
    {
      "id": "e462fb11",
      "data": {
        "text": " useful."
      }
    },
    {
      "id": "cdf63f80",
      "data": {
        "text": " fast."
      }
    }
  ]
}

E.g. Error Response:

{
    "ok": false,
    "reason": "x-auth-key or x-auth-secret missing"
  }

#   /playbook/use

This endpoint is for using stored Playbooks through API. It only requires an input text and returns the output text.

You can find the Playbook id in the settings section of a Playbook.

URL: api.grand.app/playbook/use

Method: POST

Request Format: JSON body

Response: JSON

E.g. Request body:

{
    "input": "Who is Elon Musk?",
    "playbook_id": "0qhpjSjsSTFoMh2Gm0yO" # id of the 'Answer the questions based on known facts' Playbook.
  }

E.g. Success Response:

{
    "ok": true,
    "id": "5d58663e",
    "data": {
      "text": "Elon Musk is an American entrepreneur, investor, engineer, and inventor."
    }
  }

E.g. Success Response with n: 2:

{
  "ok": true,
  "outputs": [
    {
      "id": "240b3daf",
      "data": {
        "text": "Elon Musk is an American entrepreneur, engineer, investor, and designer, best known for his work on the electric car company Tesla, SpaceX, and the tunneling venture The Boring Company."
      }
    },
    {
      "id": "ef92beac",
      "data": {
        "text": "Elon Musk is a South African-born American entrepreneur, investor, engineer, inventor, and the founder, CEO, and lead designer of SpaceX and Tesla Motors."
      }
    }
  ]
}

#   /socket/create

You can create a socket connection for realtime text generation. This endpoint returns a WebSocket URL you can connect to from a client. Have a look at our guide on using WebSockets for AI response.

URL: api.grand.app/socket/create

Method: POST

Request Format: JSON body

Response: JSON

E.g. Request body:

{
    "ttl": 3600
  }

E.g. Success Response:

{
    "ok": true,
    "ttl": 3600,
    "id": "vf93jf001",
    "url": "wss://api.grand.app/connect/6W3TjJFKID8290mnTLo/vf93jf001"
  }

#   Stop Signs

Grand only supports following stop values at the moment:

• <newline> to stop at a new line character. i.e: \n
• . Fullstop
• , Comma
• ? Question mark
• : Colon
• ; Semi-Colon
• !!!
• ###
• ///

#   Sample Python and CURL Code

Generate usage with Python

Below is a sample code in Python for using our /generate endpoint.

import json
  import requests

  headers = {
    'x-auth-key': '<Your-API-Key>',
    'x-auth-secret': '<Your-API-Secret>',
    
    'Accept': 'application/json',
  }

  text = """
  Grand API is simple, easy and
  """

  body = {
    "text": text.rstrip(), # remove trailing spaces, yields much better results.
    "model_id": "Ukg1ClHdlG03aG7cAu8J",
    "creativity": 50,
    "stop": ".",
    "max": 50,
  }

  response = requests.post('http://api.grand.app/generate', json=body, headers=headers)
  jsonResponse = response.json()

  if jsonResponse.get('ok') == False:
    print(f"Error from Grand: {jsonResponse.get('reason')}")
  else:
    print(jsonResponse.get('data').get('text'))

Generate usage with cURL

curl -XPOST 'http://api.grand.app/generate' \
  -H 'x-auth-key: <Your-API-Key>' \
  -H 'x-auth-secret: <Your-API-Secret>' \
  -H "Content-type: application/json" \
  -d '{
    "text": "Grand API is simple, easy and",
    "model_id": "Ukg1ClHdlG03aG7cAu8J",
    "creativity": 50,
    "stop": ".",
    "max": 50
  }'

Playbook API usage with Python

Sample code in Python for using our /playbook/use endpoint.

import json
  import requests

  headers = {
    'x-auth-key': '<Your-API-Key>',
    'x-auth-secret': '<Your-API-Secret>',
    
    'Accept': 'application/json',
  }

  body = {
    "input": "Who is Elon Musk?",
    "playbook_id": "0qhpjSjsSTFoMh2Gm0yO" # id of the 'Answer the questions based on known facts' Playbook: https://grand.app/playbook/0qhpjSjsSTFoMh2Gm0yO
  }

  response = requests.post('http://api.grand.app/playbook/use', json=body, headers=headers)
  jsonResponse = response.json()

  if jsonResponse.get('ok') == False:
    print(f"Error from Grand: {jsonResponse.get('reason')}")
  else:
    print(jsonResponse.get('data').get('text'))

Playbook use in cURL

curl -XPOST 'http://api.grand.app/playbook/use' \
  -H 'x-auth-key: <Your-API-Key>' \
  -H 'x-auth-secret: <Your-API-Secret>' \
  -H "Content-type: application/json" \
  -d '{
    "input": "Who is Elon Musk?",
    "playbook_id": "0qhpjSjsSTFoMh2Gm0yO"
  }'