API Documentation

Chat API
Stories API

Introduction

Welcome to the Deep Realms API documentation! You can find your API key on the profile page.

This page contains the documentation for the Stories API. If you would like to check out the Chat API, please click here.

If you would like to purchase over $300 worth of extra credits as a company, please reach out to us at contact@deeprealms.io and we will provide you with a discount.

Overview

Before you dive deeper into the API documentation, it’s worth starting with a brief overview of the general flow when generating text via the API:

  1. 1. The first step is to create a world.
  2. You can create a world via the /api/v1/worlds/create endpoint. Creating a world can take up to several minutes. Once you have triggered the creation of a world, you can check its creation status via the /api/v1/worlds/create/status endpoint.

  3. 2. After you have created a world, you can create a story, which is attached to a world.
  4. You can create a story via the /api/v1/stories/create endpoint. Once you make a request to the endpoint, a story should be created almost instantly. You can check whether a story exists by making a request to the /api/v1/stories/list or /api/v1/stories/info endpoints.

  5. 3. Once you have created a story, you can then generate more text for this particular story (you can also edit the story text before generating more).
  6. You can generate more text for a story via the /api/v1/stories/generate-text endpoint. You can check the text generation is complete via the /api/v1/stories/generate-text/status endpoint. You can also manually add text to a story, before generating more via the /api/v1/stories/add-text endpoint. You can also edit existing story text via the /api/v1/stories/editable-text endpoint.

Index

1. Worlds

1.1 /api/v1/worlds/create

1.2 /api/v1/worlds/create/status

1.3 /api/v1/worlds/delete

1.4 /api/v1/worlds/text

1.5 /api/v1/worlds/list

1.6 /api/v1/worlds/info

1.7 /api/v1/worlds/rename

1.8 /api/v1/worlds/duplicate

1.9 /api/v1/worlds/code (GET)

1.10 /api/v1/worlds/code (POST)

1.11 /api/v1/worlds/share

2. Stories

2.1 /api/v1/stories/create

2.2 /api/v1/stories/generate-text

2.3 /api/v1/stories/generate-text/status

2.4 /api/v1/stories/delete

2.5 /api/v1/stories/text

2.6 /api/v1/stories/list

2.7 /api/v1/stories/info

2.8 /api/v1/stories/editable-text (GET)

2.9 /api/v1/stories/editable-text (POST)

2.10 /api/v1/stories/add-text

2.11 /api/v1/stories/save-settings

2.12 /api/v1/stories/get-settings

2.13 /api/v1/stories/rename

2.14 /api/v1/stories/duplicate

2.15 /api/v1/stories/code (GET)

2.16 /api/v1/stories/code (POST)

2.17 /api/v1/stories/reinitialize

3. Shared Worlds

3.1 /api/v1/shared-worlds/list

3.2 /api/v1/shared-worlds/add

3.3 /api/v1/shared-worlds/delete

3.4 /api/v1/shared-worlds/upvote

Create world

POST https://www.deeprealms.io/api/v1/worlds/create

Create a world.

Request body:

world_name string required

The name of the world.

world_text string required

The text based on which the world will be created.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/worlds/create \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY" \
-d '{
  "world_name": "Atlantis",
  "world_text": "In a realm obscured by both time and tide, the city of Atlantis thrived..."
}'

Example response:

{
  "success": true,
  "data": {
    "world_id": 748201
  }
}

World creation status

GET https://www.deeprealms.io/api/v1/worlds/create/status

Check whether or not the creation of a world has been completed. The 'progress' key in the response contains an integer between 1 and 100 representing the progress made in the world creation process (100 meaning the process is complete and the world has been successfully created). Additionally, if the world has been successfully created, the 'is_ready' parameter will be set to 'true'.

Query parameters:

world_name string optional

The world name.

world_id integer optional

The world id.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/worlds/create/status?world_id=748201 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "world_id": 748201,
    "progress": 65,
    "is_ready": false
  }
}

Delete world

POST https://www.deeprealms.io/api/v1/worlds/delete

Delete a world.

Query parameters:

world_name string optional

The world name.

world_id integer optional

The world id.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/worlds/delete?world_id=748201 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true
}

Get world text

GET https://www.deeprealms.io/api/v1/worlds/text

Get the world text.

Query parameters:

world_name string optional

The world name.

world_id integer optional

The world id.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/worlds/text?world_id=748201 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "world_text": "In a realm obscured by both time and tide, the city of Atlantis thrived..."
  }
}

List worlds

GET https://www.deeprealms.io/api/v1/worlds/list

Get a list of all created worlds.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/worlds/list \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "worlds": [
      {
        "world_id": 748132,
        "world_name": "Wild Advetures",
        "created_on": "Sept. 21, 2023, 10:12 p.m.",
        "creation_status": {
          "progress": 100,
          "is_ready": true
        }
      },
      {
        "world_id": 748201,
        "world_name": "Atlantis",
        "created_on": "Sept. 23, 2023, 7:59 a.m.",
        "creation_status": {
          "progress": 100,
          "is_ready": true
        }
      }
    ]
  }
}

World info

GET https://www.deeprealms.io/api/v1/worlds/info

Get information about a world.

Query parameters:

world_name string optional

The world name.

world_id integer optional

The world id.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/worlds/info?world_id=748201 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "world_id": 748201,
    "world_name": "Atlantis",
    "created_on": "Sept. 23, 2023, 7:59 a.m.",
    "creation_status": {
      "progress": 100,
      "is_ready": true
    }
  }
}

Rename world

POST https://www.deeprealms.io/api/v1/worlds/rename

Rename a world.

Query parameters:

world_name string optional

The world name.

world_id integer optional

The world id.

Request body:

new_name string required

The new name of the world.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/worlds/rename?world_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY" \
-d '{
  "new_name": "Atlantis Part 2"
}'

Example response:

{
  "success": true
}

Duplicate world

POST https://www.deeprealms.io/api/v1/worlds/duplicate

Duplicate a world.

Query parameters:

world_name string optional

The world name.

world_id integer optional

The world id.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/worlds/duplicate?world_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true
}

Get world code

GET https://www.deeprealms.io/api/v1/worlds/code

Get the code for a world.

Query parameters:

world_name string optional

The world name.

world_id integer optional

The world id.

Request body:

code string required

The new world code.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/worlds/code?world_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "code": "x = \"some statement\"\nai.future_check(x)\n\ndef pre_generate():\n\tai.check(x)",
    "additional_credit_cost": 1,
    "last_save_datetime": "2023-11-12 17:23:58"
  }
}

Update world code

POST https://www.deeprealms.io/api/v1/worlds/code

Update the code for a world.

Query parameters:

world_name string optional

The world name.

world_id integer optional

The world id.

Request body:

code string required

The new world code.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/worlds/code?world_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY" \
-d '{
  "code": "x = \"some statement\"\nai.future_check(x)\n\ndef pre_generate():\n\tai.check(x)"
}'

Example response:

{
  "success": true,
  "data": {
    "contains_error": false,
    "error_message": null,
    "additional_credit_cost": 1,
    "last_save_datetime": "2023-11-12 17:23:58"
  }
}

Share world

POST https://www.deeprealms.io/api/v1/worlds/share

Share a world, so that everyone can enjoy it!

Query parameters:

world_name string optional

The world name of the world that should be shared.

world_id integer optional

The world id of the world that should be shared.

Request body:

name string required

The name of the shared world.

description string required

A description of the shared world (minimum 20 characters).

is_nsfw bool optional

A boolean specifying whether or not the world contains NSFW content. Default value is `false`.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/worlds/share?world_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY" \
-d '{
  "name": "Atlantis II",
  "description": "Discover the mysteries that lie in the lost city of Atlantis.",
  "is_nsfw": false
}'

Example response:

{
  "success": true,
  "data": {
    "shared_world_id": 432
  }
}

Create story

POST https://www.deeprealms.io/api/v1/stories/create

Create a story.

Request body:

story_name string required

The name of the story.

world_id int optional

The id of the world to which the story should be attached.

world_name string optional

The id of the world to which the story should be attached.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/stories/create \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY" \
-d '{
  "story_name": "Adventures in Atlantis",
  "world_id": 748201
}'

Example response:

{
  "success": true,
  "data": {
    "story_id": 149318
  }
}

Generate text

POST https://www.deeprealms.io/api/v1/stories/generate-text

Generate text for a story via a large language model.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Request body:

model_name string required

The name of the model that should be used to generate text.

action string optional

An optional string specifying the actions that should be performed by characters in the story. The AI will try to include these actions and their consequences in the text it generates.

authors_note string optional

The author's note. Add instructions here for the AI to follow.

memory_section string optional

The memory section. Add information here for the AI to remember.

nsfw bool optional (default is false)

Boolean determining whether NSFW mode be enabled.

adventure_mode bool optional (default is false)

Boolean determining whether adventure mode mode be enabled.

automatic_guidelines bool optional (default is false)

Boolean determining whether automatic guidelines be enabled.

automatic_memory bool optional (default is false)

Boolean determining whether automatic memory be enabled.

max_output_length integer optional

The maximum number of sentences that should be generated.

temperature integer optional

The temperature used in the sampling process.

world_engine_model string optional

The name of the model that should be used to handle the World Engine logic.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/stories/generate-text?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY" \
-d '{
  "model_name": "ChatGPT 1.0",
  "authors_note": "Focus on describing the scene.",
  "nsfw": true,
  "automatic_memory": true
}'

Example response:

{
  "success": true
}

Text generation status

GET https://www.deeprealms.io/api/v1/stories/generate-text/status

Get the status of a text generation.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/stories/generate-text/status?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "finished": true,
    "generated_text": "In the heart of Atlantis, the ancient crystal pulsed with an energy that seemed..."
  }
}

Delete story

POST https://www.deeprealms.io/api/v1/stories/delete

Delete a story.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/stories/delete?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true
}

Get story text

GET https://www.deeprealms.io/api/v1/stories/text

Get the story text.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/stories/text?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "story_text": "In a realm obscured by both time and tide, the city of Atlantis thrived..."
  }
}

List stories

GET https://www.deeprealms.io/api/v1/stories/list

Get a list of all created stories.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/stories/list \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "stories": [
      {
        "story_id": 132442,
        "story_name": "Wild Advetures - part1",
        "created_on": "Sept. 21, 2023, 10:28 p.m.",
        "world_id": 748132,
        "world_name": "Wild Advetures"
      },
      {
        "story_id": 149318,
        "story_name": "Adventures in Atlantis",
        "created_on": "Sept. 23, 2023, 8:07 a.m.",
        "world_id": 748201,
        "world_name": "Atlantis"
      }
    ]
  }
}

Story info

GET https://www.deeprealms.io/api/v1/stories/info

Get information about a story.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/stories/info?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "story_id": 149318,
    "story_name": "Adventures in Atlantis",
    "created_on": "Sept. 23, 2023, 8:07 a.m.",
    "world_id": 748201,
    "world_name": "Atlantis"
  }
}

Get story editable text

GET https://www.deeprealms.io/api/v1/stories/editable-text

Get the editable text of a story.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/stories/editable-text?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "editable_text": "Amidst the gleaming spires of Atlantis, Elara discovered an ancient scroll..."
  }
}

Edit story editable text

POST https://www.deeprealms.io/api/v1/stories/editable-text

Edit the editable text of a story.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Request body:

editable_text string required

The editable text of the story.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/stories/editable-text?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY" \
-d '{
  "editable_text": "Navigating through Atlantis's bustling market, Elara found a mysterious amulet..."
}'

Example response:

{
  "success": true
}

Add story text

POST https://www.deeprealms.io/api/v1/stories/add-text

Add text to a story.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Request body:

text string required

The text that should be added to the story.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/stories/info?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY" \
-d '{
  "text": "Curious and slightly unnerved, she slipped the amulet around her neck..."
}'

Example response:

{
  "success": true
}

Save story settings

POST https://www.deeprealms.io/api/v1/stories/save-settings

Save story settings via this endpoint. Please note that in order for story settings to be used when generating text, you must first retrieve them via "api/v1/stories/get-settings" endpoint, and then pass them in as paramters to the "api/v1/stories/generate-text" endpoint.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Request body:

model_name string required

The name of the model that should be used to generate text.

action string optional

An optional string specifying the actions that should be performed by characters in the story. The AI will try to include these actions and their consequences in the text it generates.

authors_note string optional

The author's note. Add instructions here for the AI to follow.

memory_section string optional

The memory section. Add information here for the AI to remember.

nsfw bool optional (default is false)

Boolean determining whether NSFW mode be enabled.

adventure_mode bool optional (default is false)

Boolean determining whether adventure mode mode be enabled.

automatic_guidelines bool optional (default is false)

Boolean determining whether automatic guidelines be enabled.

automatic_memory bool optional (default is false)

Boolean determining whether automatic memory be enabled.

max_output_length integer optional

The maximum number of sentences that should be generated.

number_of_generations integer optional

The number of times text should be generated in one go. Note, this setting cannot be passed into "api/v1/stories/generate-text".

Example request:

curl -X POST https://www.deeprealms.io/api/v1/stories/save-settings?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY" \
-d '{
  "model_name": "ChatGPT 1.0",
  "authors_note": "Focus on describing the scene.",
  "nsfw": true,
  "automatic_memory": true,
  "max_output_length": 5
}'

Example response:

{
  "success": true
}

Get story settings

GET https://www.deeprealms.io/api/v1/stories/get-settings

Get story settings via this endpoint. Please note that in order for story settings to be used when generating text, you must pass them in as paramters to the "api/v1/stories/generate-text" endpoint.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/stories/get-settings?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "model_name": "ChatGPT 1.0",
    "authors_note": "Focus on describing the scene.",
    "memory_section": "",
    "nsfw": true,
    "adventure_mode": false,
    "automatic_memory": true,
    "automatic_guidelines": false,
    "max_output_length": 5,
    "number_of_generations": null
  }
}

Rename story

POST https://www.deeprealms.io/api/v1/stories/rename

Rename a story.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Request body:

new_name string required

The new name of the story.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/stories/rename?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY" \
-d '{
  "new_name": "Atlantis Part 2"
}'

Example response:

{
  "success": true
}

Duplicate story

POST https://www.deeprealms.io/api/v1/stories/duplicate

Duplicate a story.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/stories/duplicate?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true
}

Get story code

GET https://www.deeprealms.io/api/v1/stories/code

Get the code for a story.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Request body:

code string required

The new story code.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/stories/code?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "code": "x = \"some statement\"\nai.future_check(x)\n\ndef pre_generate():\n\tai.check(x)",
    "additional_credit_cost": 1,
    "last_save_datetime": "2023-11-12 17:23:58"
  }
}

Update story code

POST https://www.deeprealms.io/api/v1/stories/code

Update the code for a story.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Request body:

code string required

The new story code.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/stories/code?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY" \
-d '{
  "code": "x = \"some statement\"\nai.future_check(x)\n\ndef pre_generate():\n\tai.check(x)"
}'

Example response:

{
  "success": true,
  "data": {
    "contains_error": false,
    "error_message": null,
    "additional_credit_cost": 1,
    "last_save_datetime": "2023-11-12 17:23:58"
  }
}

Reinitialize a story

POST https://www.deeprealms.io/api/v1/stories/reinitialize

Reinitializing a story means running all of the code in the World Engine once again. The original initialization process happens when a story is created. However, if you have changed any of the code outside of the `pre_generate` or `post_generate` functions, then it is necessary to reinitialize the story for these changes to take effect.

Query parameters:

story_name string optional

The story name.

story_id integer optional

The story id.

Request body:

code string required

The new story code.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/stories/reinitialize?story_id=149318 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY" \
-d '{
  "code": "x = \"some statement\"\nai.future_check(x)\n\ndef pre_generate():\n\tai.check(x)"
}'

Example response:

{
  "success": true,
  "data": {
    "contains_error": false,
    "error_message": null,
    "additional_credit_cost": 1,
    "last_save_datetime": "2023-11-12 17:23:58"
  }
}

List shared worlds

GET https://www.deeprealms.io/api/v1/shared-worlds/list

Get a list of all shared worlds, sorted by number of upvotes.

Example request:

curl -X GET https://www.deeprealms.io/api/v1/shared-worlds/list \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "shared_worlds": [
      {
        "name": "Backtrack: A Time Travel Tale",
        "creator": "Anonymous123",
        "tags": [
          "Interactive Story",
          "Other"
        ],
        "description": "A curious inventor travels through time, encountering historical figures...",
        "is_nsfw": false,
        "num_upvotes": 42,
        "created_on": "Oct. 15, 2023, 14:12 p.m.",
        "recommended_model_name": "ChatGPT 3.0",
        "recommended_world_engine_model_name": "ChatGPT 1.0"
      },
      {
        "name": "Atlantis II",
        "creator": "Anonymous456",
        "tags": [
          "RPG",
          "Interactive Story"
        ],
        "description": "Discover the mysteries that lie in the lost city of Atlantis.",
        "is_nsfw": false,
        "num_upvotes": 4,
        "created_on": "Oct. 27, 2023, 18:56 p.m.",
        "recommended_model_name": "Astral 2.0",
        "recommended_world_engine_model_name": "GPT-4"
      }
    ]
  }
}

Add shared world

POST https://www.deeprealms.io/api/v1/shared-worlds/add

Add a shared world to your library.

Query parameters:

world_name string optional

The shared world's name.

world_id integer optional

The shared world's id.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/shared-worlds/add?world_id=432 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true
}

Delete shared world

POST https://www.deeprealms.io/api/v1/shared-worlds/delete

Deletes a shared world, provided that you are its creator.

Query parameters:

world_name string optional

The shared world's name.

world_id integer optional

The shared world's id.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/shared-worlds/delete?world_id=432 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true
}

Upvote shared world

POST https://www.deeprealms.io/api/v1/shared-worlds/upvote

Upvote a shared world. If you have upvoted a shared world already, calling this endpoint again will cancel the upvote for the particular shared world.

Query parameters:

world_name string optional

The shared world's name.

world_id integer optional

The shared world's id.

Example request:

curl -X POST https://www.deeprealms.io/api/v1/shared-worlds/upvote?world_id=432 \
-H "Authorization: Bearer $DEEP_REALMS_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "num_upvotes": 43
  }
}