Introduction

The Semilattice API does what the app does: start projects, plan simulations against your user models, run them and read the results. Everything you create through the API is saved in your account, so you can open it in the app too. If you want an AI agent to do this for you, Semilattice MCP is the quicker route. It uses the same projects and simulations.

Authentication

Create an API key in the app under Settings → API Keys, and send it with every request:

curl https://api.semilattice.ai/v1/user-models \
  -H "Authorization: Bearer $SEMILATTICE_API_KEY"

Every endpoint is under https://api.semilattice.ai/v1. Keep your key secret: it acts as you. See Security.

SDKs

The Python and TypeScript SDKs cover user models, simulation goals and simulations: create, read, edit the plan and run. For projects, rounds and contexts, call the API directly. Both SDKs read your key from SEMILATTICE_API_KEY.

pip install semilattice

npm install semilattice

from semilattice import Semilattice

client = Semilattice()
user_models = client.user_models.list()

import Semilattice from "semilattice";

const client = new Semilattice();
const userModels = await client.userModels.list();

See the SDKs on PyPI and npm for async clients, error handling and retries.

How a simulation runs

Pick your user models

GET /v1/user-models lists the user models you can use. Pass their ids as user_model_ids.

Choose what to find out

GET /v1/simulation-schema?mode=research lists the User Research goals, and mode=journey the User Journey goals. Ask for one goal to see the inputs it needs.

Create the simulation

POST /v1/simulations with the mode, goal, inputs and user model ids. Semilattice writes the plan in the background, so poll GET /v1/simulations/{id} until its status is planned or failed.

Check the plan

Read the plan from the same endpoint, and change it with PATCH /v1/simulations/{id}/plan if you need to.

Run it and read the results

POST /v1/simulations/{id}/run, then poll GET /v1/simulations/{id} until it is completed or failed. A completed simulation has the results, the synthesis and a Markdown report. A failed one has a failure_reason: stop polling and read it.

To keep related simulations together, create a project first with POST /v1/projects and pass its id as project_id. Start a new round with POST /v1/projects/{id}/rounds when you test a new version. Simulations are planned against your context. GET /v1/context returns the one in use, and POST /v1/contexts creates one. See How Semilattice works for what each of these is.

Errors

A 401 means the key is missing or wrong. A 422 means a field is malformed, and a 400 means the request is well formed but can’t be used, such as a goal without the inputs it needs. Both say what is wrong. A 409 means the simulation or project isn’t in a state that allows the request, for example running a simulation that is still planning.

Get Started

Endpoints

Authentication

SDKs

How a simulation runs

Errors

​Authentication

​SDKs

​How a simulation runs

​Errors

Authentication

SDKs

How a simulation runs

Errors