Wallrus :: Toolbox API Documentation

Postman collection → OpenAPI spec →

Introduction

API that provides a set of components that can be used in different projects.

Base URL: https://toolbox.local.wallrus.dev

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_PROJECT_TOKEN}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

⚠️ Wallrus will provide the project token required to authenticate your requests. ⚠️

AI assistant

APIs for our openAI assistant

Generate assistant's response

POST

https://toolbox.local.wallrus.dev

/api/v1/assistant

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

message

string

required

message to be usede as prompt.

Example:

What's the capital of France?

assistant_id

string

assistant_id string it will use the default assistant_id from .env file.

Example:

asst_xxx

Auth

Bearer

Headers

Body

{ "message": "What's the capital of France?", "assistant_id": "asst_xxx" }

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/assistant" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"message\": \"What\'s the capital of France?\",
    \"assistant_id\": \"asst_xxx\"
}"

Example response:

{
    "response": "If you enjoy ..."
}

Activity Logs

APIs for logging and retrieving activity logs for the authenticated project.

List activity logs for the authenticated project.

GET

https://toolbox.local.wallrus.dev

/api/v1/activities

requires authentication

Supports optional filtering by multiple parameters.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

user_id

string

Optional. Filter activities by user ID.

Example:

sequi

type

string

Optional. Filter activities by activity type name.

Example:

image-generation.

value

integer

Optional. Filter activities by exact value match.

Example:

message

string

Optional. Filter activities by partial message match.

Example:

sequi

metadata

object

Optional. Filter activities by metadata fields.

Example:

{"Country":"Canada","Gender":"Female"}

date_range

object

Optional. Filter activities by date range.

Example:

{"start":"2023-01-01 00:00:00","end":"2023-01-31 23:59:59"}

date_range.start

string

This field is required when date_range is present. Must be a valid date.

Example:

2025-10-09T19:23:57

date_range.end

string

This field is required when date_range is present. Must be a valid date. Must be a date after or equal to date_range.start.

Example:

2108-10-21

created_at

string

Must be a valid date.

Example:

2025-10-09T19:23:57

Auth

Bearer

Headers

Query Parameters

Received response

Example request:

curl --request GET \
    --get "https://toolbox.local.wallrus.dev/api/v1/activities?user_id=sequi&type=image-generation.&value=6&message=sequi&metadata[Country]=Canada&metadata[Gender]=Female&date_range[start]=2023-01-01+00%3A00%3A00&date_range[end]=2023-01-31+23%3A59%3A59&created_at=2025-10-09T19%3A23%3A57" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "user_id": "uuid-2",
            "type": "image-generation",
            "value": 100,
            "message": "User generated an image",
            "metadata": {
                "model": "stable-diffusion",
                "Country": "Canada"
            },
            "created_at": "2025-04-25T12:00:00.000000Z"
        }
    ]
}

Create a new activity log entry.

POST

https://toolbox.local.wallrus.dev

/api/v1/activities

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

user_id

string

required

The ID of the user who performed the activity.

Example:

uuid-1.

type

string

required. The activity type.

Example:

image-generation.

value

integer

Optional. Numeric value associated with the activity.

Example:

message

string

Optional. Descriptive message for the activity.

Example:

sequi

metadata

object

Optional. Additional metadata in JSON format.

Example:

[]

Auth

Bearer

Headers

Body

{ "user_id": "uuid-1.", "type": "image-generation.", "value": 6, "message": "sequi", "metadata": [] }

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/activities" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"user_id\": \"uuid-1.\",
    \"type\": \"image-generation.\",
    \"value\": 6,
    \"message\": \"sequi\",
    \"metadata\": []
}"

Example response:

{
    "message": "Activity log created successfully."
}

List all available activity types or a specific type by ID.

GET

https://toolbox.local.wallrus.dev

/api/v1/activities/types/{id?}

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

integer

Optional. The ID of the activity type to retrieve.

Example:

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://toolbox.local.wallrus.dev/api/v1/activities/types/1" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "id": 1,
            "name": "image-generation",
            "description": "Image generation activity",
            "metadata": [
                {
                    "key": "ip",
                    "value": "127.0.0.1",
                    "active": true
                }
            ],
            "created_at": "2025-06-03T12:00:00.000000Z",
            "updated_at": "2025-06-03T12:00:00.000000Z"
        }
    ]
}

Get a summary of activity logs for the authenticated project.

GET

https://toolbox.local.wallrus.dev

/api/v1/activities/summary

requires authentication

Returns activity counts per type and the total count.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

user_id

string

Optional. Filter activities by user ID. The user must exist and belong to the authenticated project.

Example:

sequi

type

string

Optional. Filter activities by activity type name.

Example:

image-generation.

Body Parameters

user_id

string

Must be a valid UUID.

Example:

4d90902b-2925-34b1-aa9f-611860a391a0

type

string

Example:

sequi

Auth

Bearer

Headers

Query Parameters

Body

{ "user_id": "4d90902b-2925-34b1-aa9f-611860a391a0", "type": "sequi" }

Received response

Example request:

curl --request GET \
    --get "https://toolbox.local.wallrus.dev/api/v1/activities/summary?user_id=sequi&type=image-generation." \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"user_id\": \"4d90902b-2925-34b1-aa9f-611860a391a0\",
    \"type\": \"sequi\"
}"

Example response:

{
    "data": [
        {
            "type": "image-generation",
            "count": 5
        },
        {
            "type": "quiz-answer",
            "count": 3
        }
    ],
    "total_activities": 8
}

Authentication

APIs for user authentication

POST

https://toolbox.local.wallrus.dev

/api/v1/users/login/initiate

requires authentication

This endpoint initiates a 2FA request for a website. It sends a 2FA code to the user's email or phone number. And it will return the handshake ID for the 2FA process. The user must exist and be active.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

recipient

string

required

The email or phone number of the user.

Example:

user@example.com or +1234567890

Auth

Bearer

Headers

Body

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/users/login/initiate" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"recipient\": \"user@example.com or +1234567890\"
}"

Example response:

{
    "message": "2FA code sent to user@example.com",
    "data": {
        "handshake": "9bd24b7c-9208-4f4c-b388-8d6620b54cb9",
        "recipient": "user@example.com",
        "expires_at": "2024-04-16T13:55:18.919768Z",
        "user_id": "9e84e060-6057-4f67-ae22-18a7ef24114b"
    }
}

POST

https://toolbox.local.wallrus.dev

/api/v1/users/login/authenticate

requires authentication

This endpoint validates the provided 2FA code against the handshake and returns user data if successful.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

handshake

string

required

The handshake UUID generated during the 2FA initiation process.

Example:

9e88ca80-5fa3-44b7-aebf-3f517d502abb

code

string

required

The 6-digit verification code received by the user.

Example:

624983

Auth

Bearer

Headers

Body

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/users/login/authenticate" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"handshake\": \"9e88ca80-5fa3-44b7-aebf-3f517d502abb\",
    \"code\": \"624983\"
}"

Example response:

{
    "message": "Authentication successful",
    "data": {
        "user": {
            "id": "9e84e060-6057-4f67-ae22-18a7ef24114b",
            "first_name": "John",
            "last_name": "Doe",
            "username": "johndoe",
            "role": "user",
            "email": "john.doe@example.com",
            "phone": "+15145555555",
            "verified_at": "2025-04-01T12:00:00.000000Z",
            "is_active": true,
            "metadata": {
                "DOB": "01/01/1990",
                "Country": "USA"
            },
            "avatar": "https://toolbox.local.wallrus.dev/storage/public/avatars/HgnTRjf7AhrhA9cw1xHW9FgyZpzOvy2marEJGtp3.jpg"
        }
    }
}

Gemini API

APIs for interacting with the Gemini Video API.

Generate a video using the Gemini API.

POST

https://toolbox.local.wallrus.dev

/api/v1/gem/video

requires authentication

This endpoint allows to generate a video based on a prompt and an optional image. It initiates the video generation process and queues a job to poll for completion. A webhook URL is used to notify the caller when the video is ready.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

multipart/form-data

Example:

application/json

Body Parameters

image

file

optional Image file (types: jpeg, png, jpg, webp; max size: 5MB).

Example:

/tmp/phpo3v47869gqmkcipKBpA

uid

string

required

A unique identifier for the request.

Example:

"user-request-123"

prompt

string

required

The prompt to guide the video generation. Max 1000 characters.

Example:

"A cat wearing a superhero costume flying over a city"

negative_prompt

string

optional A negative prompt to guide what not to include in the video. Max 1000 characters.

Example:

"blurry, low quality"

webhook

string

required

The URL to send a POST request to when the video generation is complete.

Example:

"https://example.com/webhook/gemini-video"

sample_count

integer

optional The number of video samples to generate. Defaults to 1, Max 4.

Example:

duration_seconds

integer

optional The duration of the generated video in seconds. Defaults to 5, Max 8.

Example:

aspect_ratio

string

optional The aspect ratio of the video. Allowed values: "portrait", "landscape". Defaults to "portrait".

Example:

"landscape"

Auth

Bearer

Headers

Body

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/gem/video" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "uid="user-request-123""\
    --form "prompt="A cat wearing a superhero costume flying over a city""\
    --form "negative_prompt="blurry, low quality""\
    --form "webhook="https://example.com/webhook/gemini-video""\
    --form "sample_count=2"\
    --form "duration_seconds=5"\
    --form "aspect_ratio="landscape""\
    --form "image=@/tmp/phpo3v47869gqmkcipKBpA"

Example response:

{
    "message": "Video generation has been queued successfully.",
    "operation_name": "models/veo-2.0-generate-001/operations/12345abcdef",
    "uid": "user-request-123"
}

Stream video content from the Gemini API.

GET

https://toolbox.local.wallrus.dev

/api/v1/gem/video/{mediaId}

requires authentication

This endpoint streams video content directly from the Gemini API using the provided media ID.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

mediaId

string

required

The ID of the media to stream.

Example:

ft1rknu4azjb

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://toolbox.local.wallrus.dev/api/v1/gem/video/ft1rknu4azjb" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "Accept-Ranges": "bytes",
    "Cache-Control": "public, max-age=31536000",
    "Content-Disposition": "inline; filename=\"ft1rknu4azjb.mp4\"",
    "Content-Length": "12345678",
    "Content-Type": "video/mp4",
}

Image Generation

APIs for Stable Diffusion image generation

Get the list of variables assigned to the project.

GET

https://toolbox.local.wallrus.dev

/api/v1/sd/variables

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Auth

Bearer

Headers

Received response

Example request:

curl --request GET \
    --get "https://toolbox.local.wallrus.dev/api/v1/sd/variables" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "variables": {
        "style": [
            "80sFashion",
            "racecarDriver",
            "superHero",
            "clayman"
        ],
        "gender": [
            "male",
            "female",
            "neutral"
        ]
    }
}

Generate the image

POST

https://toolbox.local.wallrus.dev

/api/v1/sd/generate

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

multipart/form-data

Example:

application/json

Body Parameters

image

file

required

photo input to be manipulated

Example:

/tmp/phpg4nrqmgvjk4adnlkhMo

uid

required

The unique identifier for the user.

Example:

user123

style

required

select the prompts to be used.

Example:

superHero

webhook

requied

The URL where the responses will be send once the task is completed. Example https://example.com/webhook

Example:

sequi

automatic

optional

(default to false). This will control if the automatic subject description is used, any other variable describing the subject will be ignored.

Example:

sequi

controlnet

optional

The name of the image to be used as controlnet, just the name because internally it will become "coolpose1_depth.png".

Example:

coolpose1.

gender

optional

Example:

sequi

age_range

optional

Example:

sequi

body_shape

optional

Example:

sequi

hair_color

optional

Example:

sequi

hair_length

optional

Example:

sequi

hair_style

optional

Example:

sequi

skin_color

optional

Example:

sequi

facial_hair

optional

Example:

sequi

ethnicity

optional

Example:

sequi

Auth

Bearer

Headers

Body

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/sd/generate" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "uid=user123"\
    --form "style=superHero"\
    --form "webhook=sequi"\
    --form "automatic=sequi"\
    --form "controlnet=coolpose1."\
    --form "gender=sequi"\
    --form "age_range=sequi"\
    --form "body_shape=sequi"\
    --form "hair_color=sequi"\
    --form "hair_length=sequi"\
    --form "hair_style=sequi"\
    --form "skin_color=sequi"\
    --form "facial_hair=sequi"\
    --form "ethnicity=sequi"\
    --form "image=@/tmp/phpg4nrqmgvjk4adnlkhMo"

$client = new \GuzzleHttp\Client();
$url = 'https://toolbox.local.wallrus.dev/api/v1/sd/generate';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_PROJECT_TOKEN}',
            'Content-Type' => 'multipart/form-data',
            'Accept' => 'application/json',
        ],
        'multipart' => [
            [
                'name' => 'uid',
                'contents' => 'user123'
            ],
            [
                'name' => 'style',
                'contents' => 'superHero'
            ],
            [
                'name' => 'webhook',
                'contents' => 'sequi'
            ],
            [
                'name' => 'automatic',
                'contents' => 'sequi'
            ],
            [
                'name' => 'controlnet',
                'contents' => 'coolpose1.'
            ],
            [
                'name' => 'gender',
                'contents' => 'sequi'
            ],
            [
                'name' => 'age_range',
                'contents' => 'sequi'
            ],
            [
                'name' => 'body_shape',
                'contents' => 'sequi'
            ],
            [
                'name' => 'hair_color',
                'contents' => 'sequi'
            ],
            [
                'name' => 'hair_length',
                'contents' => 'sequi'
            ],
            [
                'name' => 'hair_style',
                'contents' => 'sequi'
            ],
            [
                'name' => 'skin_color',
                'contents' => 'sequi'
            ],
            [
                'name' => 'facial_hair',
                'contents' => 'sequi'
            ],
            [
                'name' => 'ethnicity',
                'contents' => 'sequi'
            ],
            [
                'name' => 'image',
                'contents' => fopen('/tmp/phpg4nrqmgvjk4adnlkhMo', 'r')
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response:

{
    "prompt_id": "f825155c-0a29-4a61-9c08-c5729c95f3b4",
    "number": 51,
    "node_errors": [],
    "server": "https://comfyui-04.wallrus.tech",
    "queue": 8
}

Upscale the image

POST

https://toolbox.local.wallrus.dev

/api/v1/sd/upscale

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

multipart/form-data

Example:

application/json

Body Parameters

image

file

required

photo input to be manipulated

Example:

/tmp/phpjlmqu6tfjhur5bjIElo

uid

required

The unique identifier for the user.

Example:

user123

webhook

requied

The URL where the responses will be send once the task is completed. Example https://example.com/webhook

Example:

sequi

Auth

Bearer

Headers

Body

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/sd/upscale" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "uid=user123"\
    --form "webhook=sequi"\
    --form "image=@/tmp/phpjlmqu6tfjhur5bjIElo"

Example response:

{
    "prompt_id": "da8ba155-b095-4c2b-b112-454526450e79",
    "number": 15,
    "node_errors": []
}

Make a video from the image

POST

https://toolbox.local.wallrus.dev

/api/v1/sd/video

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

multipart/form-data

Example:

application/json

Body Parameters

image

file

required

photo input to be manipulated

Example:

/tmp/php1udijr9h3slvbCoodGp

uid

required

The unique identifier for the user.

Example:

user123

webhook

requied

The URL where the responses will be send once the task is completed. Example https://example.com/webhook

Example:

sequi

Auth

Bearer

Headers

Body

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/sd/video" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "uid=user123"\
    --form "webhook=sequi"\
    --form "image=@/tmp/php1udijr9h3slvbCoodGp"

Example response:

{
    "prompt_id": "da8ba155-b095-4c2b-b112-454526450e79",
    "number": 15,
    "node_errors": []
}

Proxy the output media (image or video) from the ComfyUI server.

GET

https://toolbox.local.wallrus.dev

/api/v1/sd/proxy/{serverId}/{subfolder}/{filename}

The access is public, no authentication is required.

Headers

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

serverId

string

required

The server ID.

Example:

subfolder

string

required

The subfolder.

Example:

example-project

filename

string

required

The filename.

Example:

output_1.png or video_1.mp4

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://toolbox.local.wallrus.dev/api/v1/sd/proxy/1/example-project/output_1.png or video_1.mp4" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

binary media file

Prize Management

APIs for managing prizes

Get all prizes and prize pools for the authenticated project.

GET

https://toolbox.local.wallrus.dev

/api/v1/prizes

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Auth

Bearer

Headers

Received response

Example request:

curl --request GET \
    --get "https://toolbox.local.wallrus.dev/api/v1/prizes" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

[
    {
        "prizePoolId": 1,
        "order": 0,
        "prizePoolName": "Pool A",
        "prizes": [
            {
                "name": "Test Prize mollitia",
                "available_quantity": 5
            },
            {
                "name": "Test Prize sequi",
                "available_quantity": 1
            }
        ]
    }
]

Execute a draw for the given prize pool and user identifier.

POST

https://toolbox.local.wallrus.dev

/api/v1/prizes-pool/{prizePoolId}/draw

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

prizePoolId

string

required

The id of the prize pool.

Example:

Body Parameters

uid

optional

The unique identifier for the user.

Example:

user123

Auth

Bearer

Headers

URL Parameters

Body

{ "uid": "user123" }

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/prizes-pool/1/draw" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"uid\": \"user123\"
}"

Example response:

{
    "isWinner": false,
    "prize": null
}

Quiz Management

APIs for quizzes

Get all quizzes for the authenticated project.

GET

https://toolbox.local.wallrus.dev

/api/v1/quizzes

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Auth

Bearer

Headers

Received response

Example request:

curl --request GET \
    --get "https://toolbox.local.wallrus.dev/api/v1/quizzes" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

[
    {
        "id": 1,
        "name_en": "Quiz 1",
        "name_fr": "Quiz 1",
        "description_en": "Description 1",
        "description_fr": "Description 1",
        "image_en": "quiz1_en.jpg",
        "image_fr": "quiz1_fr.jpg"
    },
    {
        "id": 2,
        "name_en": "Quiz 2",
        "name_fr": "Quiz 2",
        "description_en": "Description 2",
        "description_fr": "Description 2",
        "image_en": "quiz2_en.jpg",
        "image_fr": "quiz2_fr.jpg"
    }
]

Get a quiz by ID.

GET

https://toolbox.local.wallrus.dev

/api/v1/quizzes/{id}

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The quiz ID.

Example:

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://toolbox.local.wallrus.dev/api/v1/quizzes/1" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "id": 1,
    "name_en": "Quiz 1",
    "name_fr": "Quiz 1",
    "description_en": "Description 1",
    "description_fr": "Description 1",
    "image_en": "quiz1_en.jpg",
    "image_fr": "quiz1_fr.jpg",
    "questions": [
        {
            "id": 1,
            "quiz_id": 1,
            "question_en": "Question 1",
            "question_fr": "Question 1",
            "image_en": "question1_en.jpg",
            "image_fr": "question1_fr.jpg",
            "answers": [
                {
                    "id": 1,
                    "quiz_question_id": 1,
                    "answer_en": "Answer 1",
                    "answer_fr": "Answer 1",
                    "image_en": "answer1_en.jpg",
                    "image_fr": "answer1_fr.jpg",
                    "is_correct": 1
                },
                {
                    "id": 2,
                    "quiz_question_id": 1,
                    "answer_en": "Answer 2",
                    "answer_fr": "Answer 2",
                    "image_en": "answer2_en.jpg",
                    "image_fr": "answer2_fr.jpg",
                    "is_correct": 0
                }
            ]
        }
    ]
}

Two-Factor Authentication

APIs for managing two-factor authentication

Initiate the two-factor authentication process.

POST

https://toolbox.local.wallrus.dev

/api/v1/2fa/initiate

requires authentication

This endpoint initiates a 2FA request for a website. It sends a 2FA code to the user's email or phone number. And it will return the handshake ID for the 2FA process.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

recipient

string

required

The email or phone number of the user.

Example:

user@example.com or +1234567890

Auth

Bearer

Headers

Body

{ "recipient": "user@example.com or +1234567890" }

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/2fa/initiate" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"recipient\": \"user@example.com or +1234567890\"
}"

Example response:

{
    "message": "2FA code sent to user@example.com",
    "data": {
        "handshake": "9bd24b7c-9208-4f4c-b388-8d6620b54cb9",
        "recipient": "user@example.com",
        "expires_at": "2024-04-16T13:55:18.919768Z"
    }
}

Verify the two-factor authentication code.

POST

https://toolbox.local.wallrus.dev

/api/v1/2fa/validate

requires authentication

This endpoint verifies the 2FA code sent to the user. It checks if the code is valid and not expired.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

handshake

string

required

The handshake ID for the 2FA request.

Example:

9bd24b7c-9208-4f4c-b388-8d6620b54cb9

code

string

required

The 2FA code to validate.

Example:

123456

Auth

Bearer

Headers

Body

{ "handshake": "9bd24b7c-9208-4f4c-b388-8d6620b54cb9", "code": "123456" }

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/2fa/validate" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"handshake\": \"9bd24b7c-9208-4f4c-b388-8d6620b54cb9\",
    \"code\": \"123456\"
}"

Example response:

{
    "message": "2FA verified",
    "data": {
        "handshake": "9bd24b7c-9208-4f4c-b388-8d6620b54cb9",
        "recipient": "user@example.com"
    }
}

Users Management

APIs for managing users

List all users in the project

GET

https://toolbox.local.wallrus.dev

/api/v1/users

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Auth

Bearer

Headers

Received response

Example request:

curl --request GET \
    --get "https://toolbox.local.wallrus.dev/api/v1/users" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

[
    {
        "id": "uuid-1",
        "first_name": "John",
        "last_name": "Doe",
        "username": null,
        "role": "user",
        "email": "john@example.com",
        "phone": null,
        "verified_at": null,
        "is_active": false,
        "metadata": {
            "DOB": "01/01/1970",
            "Country": "USA"
        },
        "avatar": "https://example.com/path/to/avatar1.jpg"
    },
    {
        "id": "uuid-2",
        "first_name": "John",
        "last_name": "Doe",
        "username": null,
        "role": "user",
        "email": "john.doe@example.com",
        "phone": null,
        "verified_at": null,
        "is_active": false,
        "metadata": {
            "DOB": "01/01/1970",
            "Country": "USA"
        },
        "avatar": null
    }
]

Get all available roles for users

GET

https://toolbox.local.wallrus.dev

/api/v1/users/roles

requires authentication

This endpoint returns all available roles that can be assigned to users.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Auth

Bearer

Headers

Received response

Example request:

curl --request GET \
    --get "https://toolbox.local.wallrus.dev/api/v1/users/roles" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "roles": [
        "user",
        "admin",
        "moderator",
        "guest"
    ]
}

Create a new user for a specific project

POST

https://toolbox.local.wallrus.dev

/api/v1/users

requires authentication

This endpoint accepts JSON data for user creation. All fields are optional, any validation must be done on the client side.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

first_name

string

Optional. The user's first name.

Example:

Charlize

last_name

string

Optional. The user's last name.

Example:

Theron

username

string

Optional. But unique per project. The user's username.

Example:

mango

role

string

Optional. The user's role. Default is user. Options can be user, admin, moderator, guest.

Example:

user

string

Optional. But unique per project. The user's email address.

Example:

hello@wallrus.dev

phone

string

Optional. But unique per project. The user's phone number.

Example:

+15145555555

metadata

object

Optional. A JSON object containing metadata.

Example:

{"DOB":"07\/08\/1975","Country":"South Africa"}

auto_activate

boolean

Optional. If true, user is auto-activated and 2FA is bypassed. Default: false.

Example:

false

Auth

Bearer

Headers

Body

{ "first_name": "Charlize", "last_name": "Theron", "username": "mango", "role": "user", "email": "hello@wallrus.dev", "phone": "+15145555555", "metadata": { "DOB": "07\/08\/1975", "Country": "South Africa" }, "auto_activate": false }

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/users" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"first_name\": \"Charlize\",
    \"last_name\": \"Theron\",
    \"username\": \"mango\",
    \"role\": \"user\",
    \"email\": \"hello@wallrus.dev\",
    \"phone\": \"+15145555555\",
    \"metadata\": {
        \"DOB\": \"07\\/08\\/1975\",
        \"Country\": \"South Africa\"
    },
    \"auto_activate\": false
}"

Example response:

{
    "id": "9e84e060-6057-4f67-ae22-18a7ef24114b",
    "first_name": "Charlize",
    "last_name": "Theron",
    "username": "mango",
    "role": "user",
    "email": "hello@wallrus.dev",
    "phone": "+15145555555",
    "verified_at": null,
    "is_active": false,
    "metadata": {
        "DOB": "07/08/1975",
        "Country": "South Africa"
    },
    "avatar": null,
    "handshake": "9e96985f-c18d-44a6-adf6-21ba1efb5716"
}

Verify Registration via 2FA

POST

https://toolbox.local.wallrus.dev

/api/v1/users/verify

requires authentication

This endpoint validates the provided 2FA code against the user's handshake and marks the user as verified if successful.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

handshake

string

Required. The handshake UUID generated during the 2FA initiation process.

Example:

9e88ca80-5fa3-44b7-aebf-3f517d502abb

code

string

Required. The 6-digit verification code received by the user.

Example:

624983

user_id

string

Required. The ID of the user to be verified.

Example:

9e84e060-6057-4f67-ae22-18a7ef24114b

Auth

Bearer

Headers

Body

{ "handshake": "9e88ca80-5fa3-44b7-aebf-3f517d502abb", "code": "624983", "user_id": "9e84e060-6057-4f67-ae22-18a7ef24114b" }

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/users/verify" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"handshake\": \"9e88ca80-5fa3-44b7-aebf-3f517d502abb\",
    \"code\": \"624983\",
    \"user_id\": \"9e84e060-6057-4f67-ae22-18a7ef24114b\"
}"

Example response:

{
    "message": "2FA verified",
    "data": {
        "user_id": "9e84e060-6057-4f67-ae22-18a7ef24114b"
    }
}

Get a specific user

GET

https://toolbox.local.wallrus.dev

/api/v1/users/{id}

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The ID of the user.

Example:

9e84e060-6057-4f67-ae22-18a7ef24114b

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://toolbox.local.wallrus.dev/api/v1/users/9e84e060-6057-4f67-ae22-18a7ef24114b" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "id": "9e84e060-6057-4f67-ae22-18a7ef24114b",
    "first_name": "John",
    "last_name": "Doe",
    "username": "johndoe",
    "role": "user",
    "email": "john.doe@example.com",
    "phone": "+15145555555",
    "verified_at": "2025-04-01T12:00:00.000000Z",
    "is_active": true,
    "metadata": {
        "DOB": "01/01/1990",
        "Country": "USA"
    },
    "avatar": "https://toolbox.local.wallrus.dev/storage/public/avatars/HgnTRjf7AhrhA9cw1xHW9FgyZpzOvy2marEJGtp3.jpg"
}

Resend 2FA code for user registration

POST

https://toolbox.local.wallrus.dev

/api/v1/users/{id}/regen_2fa

requires authentication

This endpoint resends a new 2FA code to the user (email or phone) for registration verification. Only allowed if the user is not yet verified.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The ID of the user.

Example:

9e84e060-6057-4f67-ae22-18a7ef24114b

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request POST \
    "https://toolbox.local.wallrus.dev/api/v1/users/9e84e060-6057-4f67-ae22-18a7ef24114b/regen_2fa" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "message": "2FA code resent to user@example.com",
    "data": {
        "handshake": "uuid",
        "recipient": "user@example.com",
        "expires_at": "2025-05-29T13:55:18.919768Z"
    }
}

Update a specific user

PUT

https://toolbox.local.wallrus.dev

/api/v1/users/{id}

requires authentication

This endpoint accepts JSON data for user updates. All fields are optional, validation must be done on the client side.

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The ID of the user to update.

Example:

9e84e060-6057-4f67-ae22-18a7ef24114b

Body Parameters

first_name

string

Optional. The user's updated first name.

Example:

Jane

last_name

string

Optional. The user's updated last name.

Example:

Smith

username

string

Optional. But unique per project. The user's updated username.

Example:

mango

role

string

Optional. The user's role. Default is user. Options can be user, admin, moderator, guest.

Example:

user

string

Optional. But unique per project. The user's updated email address.

Example:

jane.smith@example.com

phone

string

Optional. But unique per project. The user's updated phone number.

Example:

+15145556666

metadata

object

Optional. A JSON object containing updated metadata.

Example:

{"DOB":"14\/02\/1985","Country":"Canada"}

is_active

boolean

Optional. Whether the user is active.

Example:

true

Auth

Bearer

Headers

URL Parameters

Body

{ "first_name": "Jane", "last_name": "Smith", "username": "mango", "role": "user", "email": "jane.smith@example.com", "phone": "+15145556666", "metadata": { "DOB": "14\/02\/1985", "Country": "Canada" }, "is_active": true }

Received response

Example request:

curl --request PUT \
    "https://toolbox.local.wallrus.dev/api/v1/users/9e84e060-6057-4f67-ae22-18a7ef24114b" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"first_name\": \"Jane\",
    \"last_name\": \"Smith\",
    \"username\": \"mango\",
    \"role\": \"user\",
    \"email\": \"jane.smith@example.com\",
    \"phone\": \"+15145556666\",
    \"metadata\": {
        \"DOB\": \"14\\/02\\/1985\",
        \"Country\": \"Canada\"
    },
    \"is_active\": true
}"

Example response:

{
    "id": "9e84e060-6057-4f67-ae22-18a7ef24114b",
    "first_name": "Jane",
    "last_name": "Smith",
    "username": "janesmith",
    "role": "admin",
    "email": "jane.smith@example.com",
    "phone": "+15145556666",
    "verified_at": "2025-04-01T12:00:00.000000Z",
    "is_active": true,
    "metadata": {
        "DOB": "14/02/1985",
        "Country": "Canada"
    },
    "avatar": "https://toolbox.local.wallrus.dev/storage/public/avatars/HgnTRjf7AhrhA9cw1xHW9FgyZpzOvy2marEJGtp3.jpg"
}

Delete a specific user

DELETE

https://toolbox.local.wallrus.dev

/api/v1/users/{id}

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_PROJECT_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The ID of the user to delete.

Example:

9e84e060-6057-4f67-ae22-18a7ef24114b

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request DELETE \
    "https://toolbox.local.wallrus.dev/api/v1/users/9e84e060-6057-4f67-ae22-18a7ef24114b" \
    --header "Authorization: Bearer {YOUR_PROJECT_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "message": "User deleted successfully"
}

Wallrus :: Toolbox API Documentation

Wallrus :: Toolbox API Documentation

Introduction

Authenticating requests

AI assistant

Generate assistant's response

Headers

Body Parameters

Activity Logs

List activity logs for the authenticated project.

Headers

Query Parameters

Create a new activity log entry.

Headers

Body Parameters

List all available activity types or a specific type by ID.

Headers

URL Parameters

Get a summary of activity logs for the authenticated project.

Headers

Query Parameters

Body Parameters

Authentication

Initiate the two-factor authentication process.

Headers

Body Parameters

Authenticate a user

Headers

Body Parameters

Gemini API

Generate a video using the Gemini API.

Headers

Body Parameters

Stream video content from the Gemini API.

Headers

URL Parameters

Image Generation

Get the list of variables assigned to the project.

Headers

Generate the image

Headers

Body Parameters

Upscale the image

Headers

Body Parameters

Make a video from the image

Headers

Body Parameters

Proxy the output media (image or video) from the ComfyUI server.

Headers

URL Parameters

Prize Management

Get all prizes and prize pools for the authenticated project.

Headers

Execute a draw for the given prize pool and user identifier.

Headers

URL Parameters

Body Parameters

Quiz Management

Get all quizzes for the authenticated project.

Headers

Get a quiz by ID.

Headers

URL Parameters

Two-Factor Authentication

Initiate the two-factor authentication process.

Headers

Body Parameters

Verify the two-factor authentication code.

Headers

Body Parameters

Users Management

List all users in the project

Headers

Get all available roles for users

Headers

Create a new user for a specific project

Headers

Body Parameters

Verify Registration via 2FA