Getting Started with the Mind Reasoner API | Mind Reasoner API Documentation

Mind Reasoner API

See What's Really Happening

The Mind Reasoner API allows you to programmatically create digital minds, populate them with conversational data, and run powerful simulations to get an accurate preview of how the person will think, feel, say, and act in any scenario. This guide will walk you through the entire process in three core steps.

Prerequisites

Before you begin, make sure you have your API key. You can get this from your Mind Reasoner account dashboard. You will pass the API key as a Bearer token in the Authorization header of every request.

This guide provides interactive code examples in today’s most popular languages. Use the tabs to select your language—the choice will sync across all examples on the page.

$ # cURL is pre-installed on most macOS, Linux, and modern Windows systems.
> # No installation is needed.

The following examples use placeholder variables. Hover over them in the code to see what they mean and where to find their values.

The 3-Step Workflow

Step 1: Create Your First Mind

First, create a “mind.” This is the core entity that will hold the data and personality model. Send a POST request to the /minds endpoint with the name of the mind you want to create.

$ curl -X POST https://app.mindreasoner.com/api/public/v1/minds \
>   -H "Authorization: Bearer {{API_KEY}}" \
>   -H "Content-Type: application/json" \
>   -d '{"name": "{{MIND_NAME}}"}'

The API will respond with the new mind’s data. Save the id from the mind object and the id from the digitalTwin object. You will need them for the next steps.

1 {
2   "mind": {
3     "id": "123e4567-e89b-12d3-a456-426614174000", // <-- Save this mindId
4     "name": "Example Mind",
5     // ...
6   },
7   "digitalTwin": {
8     "id": "abcde123-e89b-12d3-a456-426614174001", // <-- Save this digitalTwinId
9     "name": "Default",
10     // ...
11   },
12   // ...
13 }

Step 2: Upload a Data Snapshot

Now, let’s give the mind some knowledge by uploading a data file (like a conversation transcript in .vtt, .docx, or .pdf format). This creates a snapshot of the mind’s state.

Part A: Get a Secure Upload URL

First, ask the API for a special, one-time URL to upload your file.

$ curl -X GET "https://app.mindreasoner.com/api/public/v1/minds/{{MIND_ID}}/signed-url" \
>   -H "Authorization: Bearer {{API_KEY}}"

The response will contain a signedUrl and an artifactId. Save the artifactId.

1 {
2   "signedUrl": "https://storage.googleapis.com/...", // <-- The temporary upload destination
3   "fileName": "...",
4   "artifactId": "fedcba98-e89b-12d3-a456-426614174002" // <-- Save this artifactId
5 }

Part B: Upload Your File

Next, use the signedUrl to upload your local file. This is a PUT request where the body is your file’s content.

$ curl -X PUT "{{SIGNED_URL}}" \
>   -H "Content-Type: text/vtt" \
>   --data-binary "@/path/to/your/transcript.vtt"

Part C: Create the Snapshot

Finally, tell Mind Reasoner to process the uploaded file. Send a POST request using the IDs you saved.

$ curl -X POST "https://app.mindreasoner.com/api/public/v1/minds/{{MIND_ID}}/snapshots" \
>   -H "Authorization: Bearer {{API_KEY}}" \
>   -F "digitalTwinId={{DIGITAL_TWIN_ID}}" \
>   -F "artifactId={{ARTIFACT_ID}}"

The response will give you a mindAssessmentId. Save this ID, as it’s your snapshot’s unique identifier.

1 {
2   "message": "Mind assessment started",
3   "mindAssessmentId": "98765432-e89b-12d3-a456-426614174003", // <-- Save this snapshotId
4   "artifactId": "fedcba98-e89b-12d3-a456-426614174002"
5 }

Step 3: Run Your First Simulation

Snapshot processing is asynchronous. Before you can run a simulation, you must check its status.

Check Snapshot Status

Poll the /status endpoint using your mindId and the snapshotId (mindAssessmentId) until the status is completed.

$ curl -X GET "https://app.mindreasoner.com/api/public/v1/minds/{{MIND_ID}}/snapshots/{{SNAPSHOT_ID}}/status" \
>   -H "Authorization: Bearer {{API_KEY}}"

Wait for this response:

1 {
2   "id": "98765432-e89b-12d3-a456-426614174003",
3   "status": "completed",
4   // ...
5 }

Once the snapshot is complete, you can run a simulation. Send a POST request to the /simulate endpoint with your **mindId** and a scenario.

$ curl -X POST https://app.mindreasoner.com/api/public/v1/simulate \
>   -H "Authorization: Bearer {{API_KEY}}" \
>   -H "Content-Type: application/json" \
>   -d '{
>         "mindId": "{{MIND_ID}}",
>         "selectedSimulationModel": "{{SIMULATION_MODEL}}",
>         "scenario": {
>           "message": "What would be your response to this customer complaint?"
>         }
>       }'

The API will return the simulated response from the mind.

1 {
2   "message": "Based on the provided data, my response to the customer complaint would be..."
3 }

You're Ready to Build

Congratulations! You have successfully created a mind, uploaded data, and run your first simulation. You can now integrate this workflow to bring an accurate preview of how a person will think, feel, say, and act into your own applications.

Need Help?

📖

Full API Reference

Explore all endpoints and parameters in the official API Documentation.

📧