Spike Labs API

user

Endpointhttps://api.spikelabs.com

Get memory scratchpad

GET

https://api.spikelabs.com

/content/api/memories/scratchpad

Retrieve the memory scratchpad for the current user's companion chat.

Get memory scratchpad › query Parameters

companion_id

string · uuid · required

type

string · enum

Enum values:

companion

roleplay

Default: companion

conversation_id

string · uuid

max_words

string

If provided, condense the scratchpad to fit within this word budget.

hint

string

Guidance for what to prioritize when condensing.

Get memory scratchpad › Responses

Scratchpad content

id

number · required

content

string · required

version

number · required

type

string · enum · required

Enum values:

companion

roleplay

updated_at

string · date-time · required

GET/content/api/memories/scratchpad

curl --request GET \
  --url 'https://api.spikelabs.com/content/api/memories/scratchpad?companion_id=%3Cstring%3E'

shell

Example Responses

{
  "id": 1,
  "content": "## User Profile\n- Name: Alex...",
  "version": 3,
  "type": "companion",
  "updated_at": "2025-01-01T00:00:00.000Z"
}

json

application/json

Update memory scratchpad

PUT

https://api.spikelabs.com

/content/api/memories/scratchpad

Directly update the scratchpad content. Allows users to fix incorrect memories.

Update memory scratchpad › query Parameters

companion_id

string · uuid · required

type

string · enum

Enum values:

companion

roleplay

Default: companion

conversation_id

string · uuid

Update memory scratchpad › Request Body

content

string · required

Update memory scratchpad › Responses

Updated scratchpad

id

number · required

content

string · required

version

number · required

type

string · enum · required

Enum values:

companion

roleplay

updated_at

string · date-time · required

PUT/content/api/memories/scratchpad

curl --request PUT \
  --url 'https://api.spikelabs.com/content/api/memories/scratchpad?companion_id=%3Cstring%3E' \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": "content"
}
'

shell

Example Request Body

{
  "content": "content"
}

json

Example Responses

{
  "id": 1,
  "content": "## User Profile\n- Name: Alex...",
  "version": 3,
  "type": "companion",
  "updated_at": "2025-01-01T00:00:00.000Z"
}

json

application/json

List published skins

GET

https://api.spikelabs.com

/media/api/skins

Returns a paginated list of published and enabled skins.

List published skins › query Parameters

limit

integer · min: 1 · max: 100

Default: 20

cursor

string

Cursor for pagination (base64 encoded created_at + id)

gender

string · enum

Enum values:

male

female

other

style

string · enum

Enum values:

anime

realistic

List published skins › Responses

200

List of published skins

object[] · required

object · required

GET/media/api/skins

curl --request GET \
  --url https://api.spikelabs.com/media/api/skins

shell

Example Responses

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Warrior",
      "gender": "female",
      "style": "realistic",
      "cover_photo_url": "https://cdn.example.com/skin.jpg"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJjIjoiMjAyNC0wMS0wMVQwMDowMDowMFoiLCJpIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIn0="
  }
}

json

application/json

Get published skin details

GET

https://api.spikelabs.com

/media/api/skins/{id}

Returns details for a single published skin by ID.

Get published skin details › path Parameters

id

string · uuid · required

Get published skin details › Responses

Skin details

id

string · uuid · required

name

string · required

gender

string · enum · required

Enum values:

male

female

other

style

string · enum · required

Enum values:

anime

realistic

cover_photo_url

string · required

GET/media/api/skins/{id}

curl --request GET \
  --url https://api.spikelabs.com/media/api/skins/:id

shell

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Warrior",
  "gender": "female",
  "style": "realistic",
  "cover_photo_url": "https://cdn.example.com/skin.jpg"
}

json

application/json

List user media collection

GET

https://api.spikelabs.com

/media/api/collection

Returns a paginated list of media in the user's collection with optional filters for type and favorites.

List user media collection › query Parameters

limit

integer · min: 1 · max: 1000

Default: 20

cursor

string

Cursor for pagination (base64 encoded created_at + id)

type

string · enum

Filter by media type

Enum values:

all

image

video

Default: all

favorite

Filter to only favorite items

relationType

string · enum

How the user is related to this media

Enum values:

created

saved

shared

List user media collection › Responses

200

Collection list retrieved successfully

object[] · required

object · required

GET/media/api/collection

curl --request GET \
  --url https://api.spikelabs.com/media/api/collection

shell

Example Responses

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "mediaId": "550e8400-e29b-41d4-a716-446655440001",
      "mediaType": "image",
      "cdnUrl": "https://cdn.aifiles.io/tenant/file/image.jpg",
      "relationType": "created",
      "isFavorite": false,
      "userMetadata": {
        "prompt": "A beautiful sunset over the ocean",
        "style": "realistic",
        "aspectRatio": "16:9",
        "tags": [
          "nature",
          "sunset"
        ]
      },
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "hasMore": true,
    "nextCursor": "eyJjIjoiMjAyNC0wMS0wMVQwMDowMDowMFoiLCJpIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIn0="
  }
}

json

application/json

Add media to collection

POST

https://api.spikelabs.com

/media/api/collection

Adds a media item to the user's collection. The media must exist and be accessible to the user's tenant.

Add media to collection › Request Body

mediaId

string · uuid · required

ID of the media to add to collection

relationType

string · enum

How the user is related to this media

Enum values:

created

saved

shared

Default: saved

object

Add media to collection › Responses

Media added to collection successfully

id

string · uuid · required

mediaId

string · uuid · required

mediaType

string · required

image | video | other

cdnUrl

string · uri · required

relationType

string · enum · required

How the user is related to this media

Enum values:

created

saved

shared

isFavorite

boolean · required

object · required

createdAt

string · date-time · required

POST/media/api/collection

curl --request POST \
  --url https://api.spikelabs.com/media/api/collection \
  --header 'Content-Type: application/json' \
  --data '
{
  "mediaId": "550e8400-e29b-41d4-a716-446655440001",
  "relationType": "created",
  "userMetadata": {
    "prompt": "A beautiful sunset over the ocean",
    "style": "realistic",
    "aspectRatio": "16:9",
    "tags": [
      "nature",
      "sunset"
    ]
  }
}
'

shell

Example Request Body

{
  "mediaId": "550e8400-e29b-41d4-a716-446655440001",
  "relationType": "created",
  "userMetadata": {
    "prompt": "A beautiful sunset over the ocean",
    "style": "realistic",
    "aspectRatio": "16:9",
    "tags": [
      "nature",
      "sunset"
    ]
  }
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mediaId": "550e8400-e29b-41d4-a716-446655440001",
  "mediaType": "image",
  "cdnUrl": "https://cdn.aifiles.io/tenant/file/image.jpg",
  "relationType": "created",
  "isFavorite": false,
  "userMetadata": {
    "prompt": "A beautiful sunset over the ocean",
    "style": "realistic",
    "aspectRatio": "16:9",
    "tags": [
      "nature",
      "sunset"
    ]
  },
  "createdAt": "2024-01-01T00:00:00.000Z"
}

json

application/json

Remove from collection

DELETE

https://api.spikelabs.com

/media/api/collection/{id}

Removes a media item from the user's collection. This does not delete the underlying media file.

Remove from collection › path Parameters

id

string · uuid · required

Remove from collection › Responses

Removed from collection successfully

No data returned

DELETE/media/api/collection/{id}

curl --request DELETE \
  --url https://api.spikelabs.com/media/api/collection/:id

shell

Example Responses

No example specified for this content type

Update collection item

PATCH

https://api.spikelabs.com

/media/api/collection/{id}

Update the favorite status or metadata for a collection item.

Update collection item › path Parameters

id

string · uuid · required

Update collection item › Request Body

isFavorite

boolean

object

Update collection item › Responses

Collection item updated successfully

id

string · uuid · required

mediaId

string · uuid · required

mediaType

string · required

image | video | other

cdnUrl

string · uri · required

relationType

string · enum · required

How the user is related to this media

Enum values:

created

saved

shared

isFavorite

boolean · required

object · required

createdAt

string · date-time · required

PATCH/media/api/collection/{id}

curl --request PATCH \
  --url https://api.spikelabs.com/media/api/collection/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "isFavorite": true,
  "userMetadata": {
    "prompt": "A beautiful sunset over the ocean",
    "style": "realistic",
    "aspectRatio": "16:9",
    "tags": [
      "nature",
      "sunset"
    ]
  }
}
'

shell

Example Request Body

{
  "isFavorite": true,
  "userMetadata": {
    "prompt": "A beautiful sunset over the ocean",
    "style": "realistic",
    "aspectRatio": "16:9",
    "tags": [
      "nature",
      "sunset"
    ]
  }
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mediaId": "550e8400-e29b-41d4-a716-446655440001",
  "mediaType": "image",
  "cdnUrl": "https://cdn.aifiles.io/tenant/file/image.jpg",
  "relationType": "created",
  "isFavorite": false,
  "userMetadata": {
    "prompt": "A beautiful sunset over the ocean",
    "style": "realistic",
    "aspectRatio": "16:9",
    "tags": [
      "nature",
      "sunset"
    ]
  },
  "createdAt": "2024-01-01T00:00:00.000Z"
}

json

application/json

Generate image from skin + category

POST

https://api.spikelabs.com

/media/api/generate/image/category

Generate an image for a character using a pre-defined category.

Generate image from skin + category › Request Body

skin_id

string · uuid · required

category

string · enum · required

Pre-defined category for prompt generation

Enum values:

sports_action

cozy_at_home

beach_day

night_out

workout_gym

professional_headshot

dramatic_portrait

seed

integer

user_id

string

User ID who triggered the generation (for user_media record)

activity_instance_id

string · uuid

Activity instance (chat session) ID for message delivery callback and instance-specific context (persona, recent messages)

activity_id

string · uuid

Activity ID for fetching activity-level context (image gen fields, scenario, personality). Used by studio admin or alongside activity_instance_id.

generation_mode

string · enum

When set, uses LLM to generate the prompt from chat context instead of requiring positive_prompt

Enum values:

portrait

face

user

scene

last_message

raw_last

background

free

nsfw_level

string · enum

Content explicitness level for LLM prompt generation

Enum values:

sfw

nsfw

Default: sfw

Generate image from skin + category › Responses

Generation queued successfully

job_id

string · uuid · required

generation_id

string · uuid · required

POST/media/api/generate/image/category

curl --request POST \
  --url https://api.spikelabs.com/media/api/generate/image/category \
  --header 'Content-Type: application/json' \
  --data '
{
  "skin_id": "00000000-0000-0000-0000-000000000000",
  "category": "sports_action",
  "seed": 0,
  "user_id": "user_2abc123",
  "activity_instance_id": "019abc12-def3-7890-abcd-ef1234567890",
  "activity_id": "019abc12-def3-7890-abcd-ef1234567890",
  "generation_mode": "portrait",
  "nsfw_level": "sfw"
}
'

shell

Example Request Body

{
  "skin_id": "00000000-0000-0000-0000-000000000000",
  "category": "sports_action",
  "seed": 0,
  "user_id": "user_2abc123",
  "activity_instance_id": "019abc12-def3-7890-abcd-ef1234567890",
  "activity_id": "019abc12-def3-7890-abcd-ef1234567890",
  "generation_mode": "portrait",
  "nsfw_level": "sfw"
}

json

Example Responses

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "generation_id": "550e8400-e29b-41d4-a716-446655440001"
}

json

application/json

Generate video from skin + category

POST

https://api.spikelabs.com

/media/api/generate/video/category

Generate a video for a character using a pre-defined category.

Generate video from skin + category › Request Body

skin_id

string · uuid · required

category

string · enum · required

Pre-defined category for prompt generation

Enum values:

sports_action

cozy_at_home

beach_day

night_out

workout_gym

professional_headshot

dramatic_portrait

first_frame_source

string · enum

Whether to generate first frame or use skin reference image

Enum values:

generate

reference

Default: generate

reference_image_type

string · enum

Which skin reference image to use

Enum values:

headshot_portrait

full_body_clothed_portrait

full_body_swimsuit_portrait

full_body_underwear_portrait

full_body_naked_portrait

full_body_clothed_from_behind_portrait

seed

integer

user_id

string

User ID who triggered the generation (for user_media record)

activity_instance_id

string · uuid

Activity instance (chat session) ID for message delivery callback and instance-specific context (persona, recent messages)

activity_id

string · uuid

Activity ID for fetching activity-level context (image gen fields, scenario, personality). Used by studio admin or alongside activity_instance_id.

generation_mode

string · enum

When set, uses LLM to generate the prompt from chat context instead of requiring positive_prompt

Enum values:

portrait

face

user

scene

last_message

raw_last

background

free

nsfw_level

string · enum

Content explicitness level for LLM prompt generation

Enum values:

sfw

nsfw

Default: sfw

Generate video from skin + category › Responses

Generation queued successfully

job_id

string · uuid · required

generation_id

string · uuid · required

POST/media/api/generate/video/category

curl --request POST \
  --url https://api.spikelabs.com/media/api/generate/video/category \
  --header 'Content-Type: application/json' \
  --data '
{
  "skin_id": "00000000-0000-0000-0000-000000000000",
  "category": "sports_action",
  "first_frame_source": "generate",
  "reference_image_type": "full_body_clothed_portrait",
  "seed": 0,
  "user_id": "user_2abc123",
  "activity_instance_id": "019abc12-def3-7890-abcd-ef1234567890",
  "activity_id": "019abc12-def3-7890-abcd-ef1234567890",
  "generation_mode": "portrait",
  "nsfw_level": "sfw"
}
'

shell

Example Request Body

{
  "skin_id": "00000000-0000-0000-0000-000000000000",
  "category": "sports_action",
  "first_frame_source": "generate",
  "reference_image_type": "full_body_clothed_portrait",
  "seed": 0,
  "user_id": "user_2abc123",
  "activity_instance_id": "019abc12-def3-7890-abcd-ef1234567890",
  "activity_id": "019abc12-def3-7890-abcd-ef1234567890",
  "generation_mode": "portrait",
  "nsfw_level": "sfw"
}

json

Example Responses

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "generation_id": "550e8400-e29b-41d4-a716-446655440001"
}

json

application/json

List published skins

GET

https://api.spikelabs.com

/media/api/public/skins

Returns a paginated list of published and enabled skins for the tenant.

List published skins › query Parameters

limit

integer · min: 1 · max: 100

Default: 20

cursor

string

Cursor for pagination (base64 encoded created_at + id)

gender

string · enum

Enum values:

male

female

other

style

string · enum

Enum values:

anime

realistic

List published skins › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

List published skins › Responses

List of published skins

object[] · required

object · required

GET/media/api/public/skins

curl --request GET \
  --url https://api.spikelabs.com/media/api/public/skins \
  --header 'Authorization: <string>'

shell

Example Responses

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Warrior",
      "gender": "female",
      "style": "realistic",
      "cover_photo_url": "https://cdn.example.com/skin.jpg"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJjIjoiMjAyNC0wMS0wMVQwMDowMDowMFoiLCJpIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIn0="
  }
}

json

application/json

List published activities

GET

https://api.spikelabs.com

/activity/api/activities

Returns a paginated list of published activities for the catalog. Only activities with published=true are returned.

List published activities › query Parameters

limit

integer · min: 1 · max: 100

Default: 20

cursor

string

Cursor for pagination (base64 encoded created_at + id)

category

string

featured

is_companion

List published activities › Responses

200

List of published activities

object[] · required

object · required

GET/activity/api/activities

curl --request GET \
  --url https://api.spikelabs.com/activity/api/activities

shell

Example Responses

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Stranded on a Deserted Island",
      "short_description": "Survive on a mysterious island",
      "listing_image_url": "https://cdn.example.com/island.jpg",
      "category": "Adventure",
      "subcategory": "Survival",
      "featured": false,
      "is_companion": false,
      "created_at": "2024-01-15T10:30:00.000Z",
      "anime_cover_image_url": "https://cdn.example.com/anime-cover.jpg",
      "realistic_cover_image_url": "https://cdn.example.com/realistic-cover.jpg",
      "nsfw_anime_cover_image_url": "https://cdn.example.com/nsfw-anime-cover.jpg",
      "nsfw_realistic_cover_image_url": "https://cdn.example.com/nsfw-realistic-cover.jpg"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJjIjoiMjAyNC0wMS0wMVQwMDowMDowMFoiLCJpIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIn0="
  }
}

json

application/json

Get activity details

GET

https://api.spikelabs.com

/activity/api/activities/{id}

Returns details for a single published activity. Returns 404 if the activity does not exist or is not published.

Get activity details › path Parameters

id

string · uuid · required

Get activity details › Responses

Activity details

id

string · uuid · required

title

string · required

description

string · required

short_description

string · required

scenario

string · required

example_dialogue

string · required

listing_image_url

string · uri · required

secondary_image_urls

string[] · required

category

string · required

subcategory

string · required

featured

boolean · required

is_companion

boolean · required

anime_cover_image_url

string · uri · required

realistic_cover_image_url

string · uri · required

nsfw_anime_cover_image_url

string · uri · required

nsfw_realistic_cover_image_url

string · uri · required

anime_cover_video_url

string · uri · required

realistic_cover_video_url

string · uri · required

nsfw_anime_cover_video_url

string · uri · required

nsfw_realistic_cover_video_url

string · uri · required

anime_cover_image_urls

string[] · required

realistic_cover_image_urls

string[] · required

anime_cover_video_urls

string[] · required

realistic_cover_video_urls

string[] · required

default_cover_image_prompt

string · required

anime_cover_image_prompt

string · required

realistic_cover_image_prompt

string · required

nsfw_anime_cover_image_urls

string[] · required

nsfw_realistic_cover_image_urls

string[] · required

nsfw_anime_cover_video_urls

string[] · required

nsfw_realistic_cover_video_urls

string[] · required

nsfw_default_cover_image_prompt

string · required

nsfw_anime_cover_image_prompt

string · required

nsfw_realistic_cover_image_prompt

string · required

personality

string · required

first_message

string · required

system_prompt

string · required

post_history_instructions

string · required

alternate_greetings

string[] · required

creator_notes

string · required

creator

string · required

character_version

string · required

tags

string[] · required

object · required

image_gen_character_short_text

string · required

image_gen_character_clothed_text

string · required

image_gen_character_naked_text

string · required

default_outfit_text

string · required

default_footwear_text

string · required

llm_image_prompt_generation_help_text

string · required

video_character_prompt

string · required

nsfw_video_character_prompt

string · required

anime_skin_id

string · uuid · required

realistic_skin_id

string · uuid · required

GET/activity/api/activities/{id}

curl --request GET \
  --url https://api.spikelabs.com/activity/api/activities/:id

shell

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Stranded on a Deserted Island",
  "description": "You find yourself washed up on a mysterious island...",
  "short_description": "Survive on a mysterious island",
  "scenario": "You wake up on a beach with nothing but the clothes on your back...",
  "example_dialogue": "User: Where am I?\nAssistant: *looks around nervously*...",
  "listing_image_url": "https://cdn.example.com/island.jpg",
  "secondary_image_urls": [
    "https://cdn.example.com/island2.jpg"
  ],
  "category": "Adventure",
  "subcategory": "Survival",
  "featured": false,
  "is_companion": false,
  "anime_cover_image_url": "https://cdn.example.com/anime-cover.jpg",
  "realistic_cover_image_url": "https://cdn.example.com/realistic-cover.jpg",
  "nsfw_anime_cover_image_url": "https://cdn.example.com/nsfw-anime-cover.jpg",
  "nsfw_realistic_cover_image_url": "https://cdn.example.com/nsfw-realistic-cover.jpg",
  "anime_cover_video_url": "https://cdn.example.com/anime-cover.mp4",
  "realistic_cover_video_url": "https://cdn.example.com/realistic-cover.mp4",
  "nsfw_anime_cover_video_url": "https://cdn.example.com/nsfw-anime-cover.mp4",
  "nsfw_realistic_cover_video_url": "https://cdn.example.com/nsfw-realistic-cover.mp4",
  "anime_cover_image_urls": [
    "https://cdn.example.com/anime1.jpg"
  ],
  "realistic_cover_image_urls": [
    "https://cdn.example.com/realistic1.jpg"
  ],
  "anime_cover_video_urls": [
    "https://cdn.example.com/anime1.mp4"
  ],
  "realistic_cover_video_urls": [
    "https://cdn.example.com/realistic1.mp4"
  ],
  "default_cover_image_prompt": "A fantasy landscape at sunset",
  "anime_cover_image_prompt": "Anime style fantasy landscape",
  "realistic_cover_image_prompt": "Photorealistic fantasy landscape",
  "nsfw_anime_cover_image_urls": [
    "https://cdn.example.com/nsfw-anime1.jpg"
  ],
  "nsfw_realistic_cover_image_urls": [
    "https://cdn.example.com/nsfw-realistic1.jpg"
  ],
  "nsfw_anime_cover_video_urls": [
    "https://cdn.example.com/nsfw-anime1.mp4"
  ],
  "nsfw_realistic_cover_video_urls": [
    "https://cdn.example.com/nsfw-realistic1.mp4"
  ],
  "nsfw_default_cover_image_prompt": "NSFW fantasy landscape at sunset",
  "nsfw_anime_cover_image_prompt": "NSFW anime style fantasy landscape",
  "nsfw_realistic_cover_image_prompt": "NSFW photorealistic fantasy landscape",
  "personality": "Brave and resourceful",
  "first_message": "Welcome, traveler...",
  "system_prompt": "You are a helpful guide...",
  "post_history_instructions": "Remember to stay in character",
  "alternate_greetings": [
    "Hello!",
    "Greetings!"
  ],
  "creator_notes": "Created for fantasy RP",
  "creator": "john_doe",
  "character_version": "1.0.0",
  "tags": [
    "fantasy",
    "adventure"
  ],
  "extensions": {},
  "image_gen_character_short_text": "young woman, silver hair, elf ears",
  "image_gen_character_clothed_text": "1girl, silver hair, long hair, elf ears, green eyes, medieval dress",
  "image_gen_character_naked_text": "1girl, silver hair, long hair, elf ears, green eyes, nude",
  "default_outfit_text": "medieval dress, leather boots, silver necklace",
  "default_footwear_text": "leather boots",
  "llm_image_prompt_generation_help_text": "Fantasy setting, medieval aesthetic, forest environment",
  "video_character_prompt": "silver-haired elf woman in a medieval dress",
  "nsfw_video_character_prompt": "NSFW silver-haired elf woman in a medieval dress",
  "anime_skin_id": "550e8400-e29b-41d4-a716-446655440001",
  "realistic_skin_id": "550e8400-e29b-41d4-a716-446655440003"
}

json

application/json

List user's activity instances

GET

https://api.spikelabs.com

/activity/api/activity-instances

Returns a paginated list of activity instances belonging to the authenticated user.

List user's activity instances › query Parameters

limit

integer · min: 1 · max: 100

Default: 20

cursor

string

Cursor for pagination (base64 encoded created_at + id)

status

string · enum

Enum values:

active

archived

activity_id

string · uuid

List user's activity instances › Responses

List of user's activity instances

object[] · required

object · required

GET/activity/api/activity-instances

curl --request GET \
  --url https://api.spikelabs.com/activity/api/activity-instances

shell

Example Responses

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "activity_id": "660e8400-e29b-41d4-a716-446655440000",
      "snapshot_title": "Stranded on a Deserted Island",
      "snapshot_short_description": "Survive on a mysterious island",
      "snapshot_listing_image_url": "https://cdn.example.com/island.jpg",
      "snapshot_category": "Adventure",
      "status": "active",
      "last_accessed_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJjIjoiMjAyNC0wMS0wMVQwMDowMDowMFoiLCJpIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIn0="
  }
}

json

application/json

Create activity instance

POST

https://api.spikelabs.com

/activity/api/activity-instances

Creates a new activity instance from a published activity. Snapshots the activity data at creation time.

Create activity instance › Request Body

activity_id

string · uuid · required

assigned_voice_id

string · uuid

Create activity instance › Responses

Instance created successfully

id

string · uuid · required

snapshot_title

string · required

snapshot_description

string · required

snapshot_short_description

string · required

snapshot_scenario

string · required

snapshot_example_dialogue

string · required

snapshot_listing_image_url

string · uri · required

snapshot_secondary_image_urls

string[] · required

snapshot_category

string · required

snapshot_subcategory

string · required

snapshot_personality

string · required

snapshot_first_message

string · required

snapshot_system_prompt

string · required

snapshot_post_history_instructions

string · required

snapshot_alternate_greetings

string[] · required

snapshot_lorebook_ids

string[] · required

assigned_voice_id

string · uuid · required

status

string · enum · required

Enum values:

active

archived

last_accessed_at

string · date-time · required

created_at

string · date-time · required

POST/activity/api/activity-instances

curl --request POST \
  --url https://api.spikelabs.com/activity/api/activity-instances \
  --header 'Content-Type: application/json' \
  --data '
{
  "activity_id": "660e8400-e29b-41d4-a716-446655440000",
  "assigned_voice_id": "aa0e8400-e29b-41d4-a716-446655440000"
}
'

shell

Example Request Body

{
  "activity_id": "660e8400-e29b-41d4-a716-446655440000",
  "assigned_voice_id": "aa0e8400-e29b-41d4-a716-446655440000"
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "snapshot_title": "Stranded on a Deserted Island",
  "snapshot_description": "You find yourself washed up on a mysterious island...",
  "snapshot_short_description": "Survive on a mysterious island",
  "snapshot_scenario": "You wake up on a beach with nothing but the clothes on your back...",
  "snapshot_example_dialogue": "User: Where am I?\nAssistant: *looks around nervously*...",
  "snapshot_listing_image_url": "https://cdn.example.com/island.jpg",
  "snapshot_secondary_image_urls": [
    "https://cdn.example.com/island2.jpg"
  ],
  "snapshot_category": "Adventure",
  "snapshot_subcategory": "Survival",
  "snapshot_personality": "Brave and resourceful",
  "snapshot_first_message": "Welcome, traveler...",
  "snapshot_system_prompt": "You are a helpful guide...",
  "snapshot_post_history_instructions": "Remember to stay in character",
  "snapshot_alternate_greetings": [
    "Hello!",
    "Greetings!"
  ],
  "snapshot_lorebook_ids": [
    "bb0e8400-e29b-41d4-a716-446655440000"
  ],
  "assigned_voice_id": "aa0e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "last_accessed_at": "2024-01-01T00:00:00.000Z",
  "created_at": "2024-01-01T00:00:00.000Z"
}

json

application/json

Get activity instance details

GET

https://api.spikelabs.com

/activity/api/activity-instances/{id}

Returns details for a single activity instance. Only accessible by the instance owner. Updates the last_accessed_at timestamp.

Get activity instance details › path Parameters

id

string · uuid · required

Get activity instance details › Responses

Activity instance details

id

string · uuid · required

snapshot_title

string · required

snapshot_description

string · required

snapshot_short_description

string · required

snapshot_scenario

string · required

snapshot_example_dialogue

string · required

snapshot_listing_image_url

string · uri · required

snapshot_secondary_image_urls

string[] · required

snapshot_category

string · required

snapshot_subcategory

string · required

snapshot_personality

string · required

snapshot_first_message

string · required

snapshot_system_prompt

string · required

snapshot_post_history_instructions

string · required

snapshot_alternate_greetings

string[] · required

snapshot_lorebook_ids

string[] · required

assigned_voice_id

string · uuid · required

status

string · enum · required

Enum values:

active

archived

last_accessed_at

string · date-time · required

created_at

string · date-time · required

GET/activity/api/activity-instances/{id}

curl --request GET \
  --url https://api.spikelabs.com/activity/api/activity-instances/:id

shell

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "snapshot_title": "Stranded on a Deserted Island",
  "snapshot_description": "You find yourself washed up on a mysterious island...",
  "snapshot_short_description": "Survive on a mysterious island",
  "snapshot_scenario": "You wake up on a beach with nothing but the clothes on your back...",
  "snapshot_example_dialogue": "User: Where am I?\nAssistant: *looks around nervously*...",
  "snapshot_listing_image_url": "https://cdn.example.com/island.jpg",
  "snapshot_secondary_image_urls": [
    "https://cdn.example.com/island2.jpg"
  ],
  "snapshot_category": "Adventure",
  "snapshot_subcategory": "Survival",
  "snapshot_personality": "Brave and resourceful",
  "snapshot_first_message": "Welcome, traveler...",
  "snapshot_system_prompt": "You are a helpful guide...",
  "snapshot_post_history_instructions": "Remember to stay in character",
  "snapshot_alternate_greetings": [
    "Hello!",
    "Greetings!"
  ],
  "snapshot_lorebook_ids": [
    "bb0e8400-e29b-41d4-a716-446655440000"
  ],
  "assigned_voice_id": "aa0e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "last_accessed_at": "2024-01-01T00:00:00.000Z",
  "created_at": "2024-01-01T00:00:00.000Z"
}

json

application/json

Delete activity instance

DELETE

https://api.spikelabs.com

/activity/api/activity-instances/{id}

Permanently deletes an activity instance and all associated messages.

Delete activity instance › path Parameters

id

string · uuid · required

Delete activity instance › Responses

Instance deleted successfully

No data returned

DELETE/activity/api/activity-instances/{id}

curl --request DELETE \
  --url https://api.spikelabs.com/activity/api/activity-instances/:id

shell

Example Responses

No example specified for this content type

Update activity instance

PATCH

https://api.spikelabs.com

/activity/api/activity-instances/{id}

Updates an activity instance. Can change assigned voice or archive the instance.

Update activity instance › path Parameters

id

string · uuid · required

Update activity instance › Request Body

assigned_voice_id

string · uuid

status

string · enum

Enum values:

active

archived

Update activity instance › Responses

Instance updated successfully

id

string · uuid · required

snapshot_title

string · required

snapshot_description

string · required

snapshot_short_description

string · required

snapshot_scenario

string · required

snapshot_example_dialogue

string · required

snapshot_listing_image_url

string · uri · required

snapshot_secondary_image_urls

string[] · required

snapshot_category

string · required

snapshot_subcategory

string · required

snapshot_personality

string · required

snapshot_first_message

string · required

snapshot_system_prompt

string · required

snapshot_post_history_instructions

string · required

snapshot_alternate_greetings

string[] · required

snapshot_lorebook_ids

string[] · required

assigned_voice_id

string · uuid · required

status

string · enum · required

Enum values:

active

archived

last_accessed_at

string · date-time · required

created_at

string · date-time · required

PATCH/activity/api/activity-instances/{id}

curl --request PATCH \
  --url https://api.spikelabs.com/activity/api/activity-instances/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "assigned_voice_id": "aa0e8400-e29b-41d4-a716-446655440000",
  "status": "archived"
}
'

shell

Example Request Body

{
  "assigned_voice_id": "aa0e8400-e29b-41d4-a716-446655440000",
  "status": "archived"
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "snapshot_title": "Stranded on a Deserted Island",
  "snapshot_description": "You find yourself washed up on a mysterious island...",
  "snapshot_short_description": "Survive on a mysterious island",
  "snapshot_scenario": "You wake up on a beach with nothing but the clothes on your back...",
  "snapshot_example_dialogue": "User: Where am I?\nAssistant: *looks around nervously*...",
  "snapshot_listing_image_url": "https://cdn.example.com/island.jpg",
  "snapshot_secondary_image_urls": [
    "https://cdn.example.com/island2.jpg"
  ],
  "snapshot_category": "Adventure",
  "snapshot_subcategory": "Survival",
  "snapshot_personality": "Brave and resourceful",
  "snapshot_first_message": "Welcome, traveler...",
  "snapshot_system_prompt": "You are a helpful guide...",
  "snapshot_post_history_instructions": "Remember to stay in character",
  "snapshot_alternate_greetings": [
    "Hello!",
    "Greetings!"
  ],
  "snapshot_lorebook_ids": [
    "bb0e8400-e29b-41d4-a716-446655440000"
  ],
  "assigned_voice_id": "aa0e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "last_accessed_at": "2024-01-01T00:00:00.000Z",
  "created_at": "2024-01-01T00:00:00.000Z"
}

json

application/json

List messages in instance

GET

https://api.spikelabs.com

/activity/api/activity-instances/{instanceId}/messages

Returns a paginated list of messages in an activity instance owned by the authenticated user.

List messages in instance › path Parameters

instanceId

string · uuid · required

List messages in instance › query Parameters

limit

integer · min: 1 · max: 100

Default: 20

cursor

string

Cursor for pagination (base64 encoded created_at + id)

role

string · enum

Enum values:

user

assistant

system

medium

string · enum

Enum values:

app

imessage

List messages in instance › Responses

List of messages

object[] · required

object · required

GET/activity/api/activity-instances/{instanceId}/messages

curl --request GET \
  --url https://api.spikelabs.com/activity/api/activity-instances/:instanceId/messages

shell

Example Responses

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "role": "user",
      "medium": "app",
      "content": "Hello, where am I?",
      "attachments": [
        {
          "url": "https://cdn.example.com/image.jpg",
          "type": "image"
        }
      ],
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJjIjoiMjAyNC0wMS0wMVQwMDowMDowMFoiLCJpIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIn0="
  }
}

json

application/json

Create message

POST

https://api.spikelabs.com

/activity/api/activity-instances/{instanceId}/messages

Creates a new message in an activity instance. Updates the instance's last_accessed_at timestamp. Cannot add messages to archived instances.

Create message › path Parameters

instanceId

string · uuid · required

Create message › Request Body

role

string · enum · required

Enum values:

user

assistant

system

medium

string · enum · required

Enum values:

app

imessage

content

string · minLength: 1 · required

object[]

Create message › Responses

Message created successfully

id

string · uuid · required

role

string · enum · required

Enum values:

user

assistant

system

medium

string · enum · required

Enum values:

app

imessage

content

string · required

object[] · required

created_at

string · date-time · required

POST/activity/api/activity-instances/{instanceId}/messages

curl --request POST \
  --url https://api.spikelabs.com/activity/api/activity-instances/:instanceId/messages \
  --header 'Content-Type: application/json' \
  --data '
{
  "role": "user",
  "medium": "app",
  "content": "Hello, where am I?",
  "attachments": [
    {
      "url": "https://cdn.example.com/image.jpg",
      "type": "image"
    }
  ]
}
'

shell

Example Request Body

{
  "role": "user",
  "medium": "app",
  "content": "Hello, where am I?",
  "attachments": [
    {
      "url": "https://cdn.example.com/image.jpg",
      "type": "image"
    }
  ]
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "role": "user",
  "medium": "app",
  "content": "Hello, where am I?",
  "attachments": [
    {
      "url": "https://cdn.example.com/image.jpg",
      "type": "image"
    }
  ],
  "created_at": "2024-01-01T00:00:00.000Z"
}

json

application/json

Get message details

GET

https://api.spikelabs.com

/activity/api/activity-instances/{instanceId}/messages/{messageId}

Returns details for a single message in an activity instance owned by the authenticated user.

Get message details › path Parameters

instanceId

string · uuid · required

messageId

string · uuid · required

Get message details › Responses

Message details

id

string · uuid · required

role

string · enum · required

Enum values:

user

assistant

system

medium

string · enum · required

Enum values:

app

imessage

content

string · required

object[] · required

created_at

string · date-time · required

GET/activity/api/activity-instances/{instanceId}/messages/{messageId}

curl --request GET \
  --url https://api.spikelabs.com/activity/api/activity-instances/:instanceId/messages/:messageId

shell

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "role": "user",
  "medium": "app",
  "content": "Hello, where am I?",
  "attachments": [
    {
      "url": "https://cdn.example.com/image.jpg",
      "type": "image"
    }
  ],
  "created_at": "2024-01-01T00:00:00.000Z"
}

json

application/json

Delete message

DELETE

https://api.spikelabs.com

/activity/api/activity-instances/{instanceId}/messages/{messageId}

Permanently deletes a message from an activity instance owned by the authenticated user.

Delete message › path Parameters

instanceId

string · uuid · required

messageId

string · uuid · required

Delete message › Responses

Message deleted successfully

No data returned

DELETE/activity/api/activity-instances/{instanceId}/messages/{messageId}

curl --request DELETE \
  --url https://api.spikelabs.com/activity/api/activity-instances/:instanceId/messages/:messageId

shell

Example Responses

No example specified for this content type

Update message

PATCH

https://api.spikelabs.com

/activity/api/activity-instances/{instanceId}/messages/{messageId}

Updates a message's content in an activity instance owned by the authenticated user.

Update message › path Parameters

instanceId

string · uuid · required

messageId

string · uuid · required

Update message › Request Body

content

string · minLength: 1

Update message › Responses

Message updated successfully

id

string · uuid · required

role

string · enum · required

Enum values:

user

assistant

system

medium

string · enum · required

Enum values:

app

imessage

content

string · required

object[] · required

created_at

string · date-time · required

PATCH/activity/api/activity-instances/{instanceId}/messages/{messageId}

curl --request PATCH \
  --url https://api.spikelabs.com/activity/api/activity-instances/:instanceId/messages/:messageId \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": "Updated message content"
}
'

shell

Example Request Body

{
  "content": "Updated message content"
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "role": "user",
  "medium": "app",
  "content": "Hello, where am I?",
  "attachments": [
    {
      "url": "https://cdn.example.com/image.jpg",
      "type": "image"
    }
  ],
  "created_at": "2024-01-01T00:00:00.000Z"
}

json

application/json

Stream chat response

POST

https://api.spikelabs.com

/activity/api/activity-instances/{instanceId}/chat

Sends a user message and streams the AI response as plain text.

The response is a streaming text body where each chunk is a piece of the assistant's response. When the stream closes, the assistant message has been saved to the database.

Example:

Code
 
POST /api/activity-instances/{instanceId}/chat
Content-Type: application/json
{"content": "Hello!"}

→ 200 OK
Content-Type: text/plain; charset=utf-8

Hello! How can I help you today?

Stream chat response › path Parameters

instanceId

string · uuid · required

Stream chat response › Request Body

content

string · minLength: 1 · maxLength: 10000 · required

The message content to send

medium

string · enum

The medium through which the message was sent

Enum values:

app

imessage

Default: app

skin_id

string

Skin ID for play mode XP scoping. When provided, XP is awarded scoped to this skin.

Stream chat response › Responses

Streaming text response from the AI

string

Streaming text response

POST/activity/api/activity-instances/{instanceId}/chat

curl --request POST \
  --url https://api.spikelabs.com/activity/api/activity-instances/:instanceId/chat \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": "Hello, how are you?",
  "medium": "app",
  "skin_id": "skin_id"
}
'

shell

Example Request Body

{
  "content": "Hello, how are you?",
  "medium": "app",
  "skin_id": "skin_id"
}

json

Example Responses

string

plain

text/plain

List user personas

GET

https://api.spikelabs.com

/activity/api/personas

Returns all personas for the authenticated user.

List user personas › Responses

200

List of personas

object[] · required

GET/activity/api/personas

curl --request GET \
  --url https://api.spikelabs.com/activity/api/personas

shell

Example Responses

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Alex",
      "gender": "male",
      "description": "A brave adventurer",
      "style_preference": "realistic",
      "is_default": true,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

json

application/json

Create persona

POST

https://api.spikelabs.com

/activity/api/personas

Creates a new persona for the authenticated user.

Create persona › Request Body

name

string · minLength: 1 · maxLength: 255 · required

gender

string · enum

Gender for pronoun substitution in templates

Enum values:

male

female

neutral

non_binary

other

description

string · maxLength: 1000

style_preference

string · enum

User's preferred image style for character displays

Enum values:

realistic

anime

is_default

boolean

Create persona › Responses

Persona created

id

string · uuid · required

name

string · required

gender

string · enum · required

Gender for pronoun substitution in templates

Enum values:

male

female

neutral

non_binary

other

description

string · required

style_preference

string · enum · required

User's preferred image style for character displays

Enum values:

realistic

anime

is_default

boolean · required

created_at

string · date-time · required

updated_at

string · date-time · required

POST/activity/api/personas

curl --request POST \
  --url https://api.spikelabs.com/activity/api/personas \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Alex",
  "gender": "male",
  "description": "A brave adventurer",
  "style_preference": "realistic",
  "is_default": false
}
'

shell

Example Request Body

{
  "name": "Alex",
  "gender": "male",
  "description": "A brave adventurer",
  "style_preference": "realistic",
  "is_default": false
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Alex",
  "gender": "male",
  "description": "A brave adventurer",
  "style_preference": "realistic",
  "is_default": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

json

application/json

Get persona

GET

https://api.spikelabs.com

/activity/api/personas/{id}

Returns a single persona by ID.

Get persona › path Parameters

id

string · uuid · required

Get persona › Responses

Persona details

id

string · uuid · required

name

string · required

gender

string · enum · required

Gender for pronoun substitution in templates

Enum values:

male

female

neutral

non_binary

other

description

string · required

style_preference

string · enum · required

User's preferred image style for character displays

Enum values:

realistic

anime

is_default

boolean · required

created_at

string · date-time · required

updated_at

string · date-time · required

GET/activity/api/personas/{id}

curl --request GET \
  --url https://api.spikelabs.com/activity/api/personas/:id

shell

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Alex",
  "gender": "male",
  "description": "A brave adventurer",
  "style_preference": "realistic",
  "is_default": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

json

application/json

Delete persona

DELETE

https://api.spikelabs.com

/activity/api/personas/{id}

Deletes a persona.

Delete persona › path Parameters

id

string · uuid · required

Delete persona › Responses

Persona deleted

No data returned

DELETE/activity/api/personas/{id}

curl --request DELETE \
  --url https://api.spikelabs.com/activity/api/personas/:id

shell

Example Responses

No example specified for this content type

Update persona

PATCH

https://api.spikelabs.com

/activity/api/personas/{id}

Updates an existing persona.

Update persona › path Parameters

id

string · uuid · required

Update persona › Request Body

name

string · minLength: 1 · maxLength: 255

gender

string · enum

Gender for pronoun substitution in templates

Enum values:

male

female

neutral

non_binary

other

description

string · maxLength: 1000

style_preference

string · enum

User's preferred image style for character displays

Enum values:

realistic

anime

Update persona › Responses

Persona updated

id

string · uuid · required

name

string · required

gender

string · enum · required

Gender for pronoun substitution in templates

Enum values:

male

female

neutral

non_binary

other

description

string · required

style_preference

string · enum · required

User's preferred image style for character displays

Enum values:

realistic

anime

is_default

boolean · required

created_at

string · date-time · required

updated_at

string · date-time · required

PATCH/activity/api/personas/{id}

curl --request PATCH \
  --url https://api.spikelabs.com/activity/api/personas/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Alex",
  "gender": "male",
  "description": "A brave adventurer",
  "style_preference": "realistic"
}
'

shell

Example Request Body

{
  "name": "Alex",
  "gender": "male",
  "description": "A brave adventurer",
  "style_preference": "realistic"
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Alex",
  "gender": "male",
  "description": "A brave adventurer",
  "style_preference": "realistic",
  "is_default": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

json

application/json

Set default persona

POST

https://api.spikelabs.com

/activity/api/personas/{id}/default

Sets a persona as the user's default.

Set default persona › path Parameters

id

string · uuid · required

Set default persona › Responses

Persona set as default

id

string · uuid · required

name

string · required

gender

string · enum · required

Gender for pronoun substitution in templates

Enum values:

male

female

neutral

non_binary

other

description

string · required

style_preference

string · enum · required

User's preferred image style for character displays

Enum values:

realistic

anime

is_default

boolean · required

created_at

string · date-time · required

updated_at

string · date-time · required

POST/activity/api/personas/{id}/default

curl --request POST \
  --url https://api.spikelabs.com/activity/api/personas/:id/default

shell

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Alex",
  "gender": "male",
  "description": "A brave adventurer",
  "style_preference": "realistic",
  "is_default": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

json

application/json

public Public Forms