> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semilattice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Plan and run simulations from your own code.

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](/mcp/introduction) 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:

```bash theme={null}
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](/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`.

```bash Python theme={null}
pip install semilattice
```

```bash TypeScript theme={null}
npm install semilattice
```

```python Python theme={null}
from semilattice import Semilattice

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

```ts TypeScript theme={null}
import Semilattice from "semilattice";

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

See the SDKs on [PyPI](https://pypi.org/project/semilattice/) and [npm](https://www.npmjs.com/package/semilattice) for async clients, error handling and retries.

## How a simulation runs

**1. Pick your user models**

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

**2. Choose what to find out**

`GET /v1/simulation-schema?mode=research` lists the [User Research](/how-it-works#simulations) goals, and `mode=journey` the User Journey goals. Ask for one goal to see the inputs it needs.

**3. 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`.

**4. Check the plan**

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

**5. 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](/how-it-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.