openapi: 3.1.0
info:
  title: Semilattice API
  description: API for human behaviour simulation.
  contact:
    name: Semilattice API
    url: https://semilattice.ai/
    email: support@semilattice.ai
  version: v1.0.0
paths:
  /v1/user-models:
    get:
      tags:
        - User Models
      summary: List user models
      description: |-
        List user models available to run simulations against, with accuracy
        and metadata. Use the ids as `user_model_ids`.
      operationId: list_user_models_route_v1_user_models_get
      parameters:
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Semilattice from 'semilattice';

            const client = new Semilattice({
              apiKey: process.env['SEMILATTICE_API_KEY'], // This is the default and can be omitted
            });

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

            console.log(userModels);
        - lang: Python
          source: |-
            import os
            from semilattice import Semilattice

            client = Semilattice(
                api_key=os.environ.get("SEMILATTICE_API_KEY"),  # This is the default and can be omitted
            )
            user_models = client.user_models.list()
            print(user_models)
  /v1/simulation-schema:
    get:
      tags:
        - Simulation Schema
      summary: Discover goals and inputs
      description: |-
        Return a mode's goal list when `goal` is omitted, or a single goal's
        input schema when `goal` is given. `mode` is `research` or `journey`.
      operationId: get_simulation_schema_v1_simulation_schema_get
      parameters:
        - name: mode
          in: query
          required: true
          schema:
            type: string
            title: Mode
        - name: goal
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Goal
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Semilattice from 'semilattice';


            const client = new Semilattice({
              apiKey: process.env['SEMILATTICE_API_KEY'], // This is the default and can be omitted
            });


            const simulationSchema = await client.simulationSchema.retrieve({
            mode: 'mode' });


            console.log(simulationSchema);
        - lang: Python
          source: |-
            import os
            from semilattice import Semilattice

            client = Semilattice(
                api_key=os.environ.get("SEMILATTICE_API_KEY"),  # This is the default and can be omitted
            )
            simulation_schema = client.simulation_schema.retrieve(
                mode="mode",
            )
            print(simulation_schema)
  /v1/simulations:
    get:
      tags:
        - Simulations
      summary: List simulations
      description: |-
        List the caller's simulations, newest first. Optionally filter by status
        or by project_id (projects group related simulations).
      operationId: list_simulations_route_v1_simulations_get
      parameters:
        - name: status_filter
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Status Filter
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            title: Limit
        - name: project_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            title: Project Id
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Semilattice from 'semilattice';

            const client = new Semilattice({
              apiKey: process.env['SEMILATTICE_API_KEY'], // This is the default and can be omitted
            });

            const simulations = await client.simulations.list();

            console.log(simulations);
        - lang: Python
          source: |-
            import os
            from semilattice import Semilattice

            client = Semilattice(
                api_key=os.environ.get("SEMILATTICE_API_KEY"),  # This is the default and can be omitted
            )
            simulations = client.simulations.list()
            print(simulations)
    post:
      tags:
        - Simulations
      summary: Create a simulation
      description: |-
        Create a simulation from mode + goal + inputs + user_model_ids.

        Returns immediately in status `planning`; the plan is generated in the
        background. Poll GET /{id} until status is `planned`.
      operationId: create_simulation_route_v1_simulations_post
      parameters:
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSimulationBody'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Semilattice from 'semilattice';

            const client = new Semilattice({
              apiKey: process.env['SEMILATTICE_API_KEY'], // This is the default and can be omitted
            });

            const simulation = await client.simulations.create({
              goal: 'goal',
              mode: 'mode',
              user_model_ids: ['182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'],
            });

            console.log(simulation);
        - lang: Python
          source: |-
            import os
            from semilattice import Semilattice

            client = Semilattice(
                api_key=os.environ.get("SEMILATTICE_API_KEY"),  # This is the default and can be omitted
            )
            simulation = client.simulations.create(
                goal="goal",
                mode="mode",
                user_model_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
            )
            print(simulation)
  /v1/simulations/{simulation_id}:
    get:
      tags:
        - Simulations
      summary: Get a simulation
      description: |-
        Fetch a simulation by id. The polling target: returns progress while
        running, and synthesis + markdown + results once completed.
      operationId: get_simulation_route_v1_simulations__simulation_id__get
      parameters:
        - name: simulation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Simulation Id
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Semilattice from 'semilattice';


            const client = new Semilattice({
              apiKey: process.env['SEMILATTICE_API_KEY'], // This is the default and can be omitted
            });


            const simulation = await
            client.simulations.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');


            console.log(simulation);
        - lang: Python
          source: |-
            import os
            from semilattice import Semilattice

            client = Semilattice(
                api_key=os.environ.get("SEMILATTICE_API_KEY"),  # This is the default and can be omitted
            )
            simulation = client.simulations.retrieve(
                "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
            )
            print(simulation)
    patch:
      tags:
        - Simulations
      summary: Move a simulation into a project
      description: >-
        Move a simulation into a project. Allowed only when the simulation has
        no

        project yet; it joins the project's latest round (a first round is
        created

        for an empty project). Anything else returns 409.
      operationId: move_simulation_route_v1_simulations__simulation_id__patch
      parameters:
        - name: simulation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Simulation Id
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveSimulationBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/simulations/{simulation_id}/plan:
    patch:
      tags:
        - Simulations
      summary: Edit the plan
      description: Edit the generated plan while the simulation is in status `planned`.
      operationId: update_plan_route_v1_simulations__simulation_id__plan_patch
      parameters:
        - name: simulation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Simulation Id
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePlanBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Semilattice from 'semilattice';


            const client = new Semilattice({
              apiKey: process.env['SEMILATTICE_API_KEY'], // This is the default and can be omitted
            });


            const response = await
            client.simulations.updatePlan('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');


            console.log(response);
        - lang: Python
          source: |-
            import os
            from semilattice import Semilattice

            client = Semilattice(
                api_key=os.environ.get("SEMILATTICE_API_KEY"),  # This is the default and can be omitted
            )
            response = client.simulations.update_plan(
                simulation_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
            )
            print(response)
  /v1/simulations/{simulation_id}/run:
    post:
      tags:
        - Simulations
      summary: Run a simulation
      description: Kick off background execution of a `planned` simulation (→ `running`).
      operationId: run_simulation_route_v1_simulations__simulation_id__run_post
      parameters:
        - name: simulation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Simulation Id
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Semilattice from 'semilattice';


            const client = new Semilattice({
              apiKey: process.env['SEMILATTICE_API_KEY'], // This is the default and can be omitted
            });


            const response = await
            client.simulations.run('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');


            console.log(response);
        - lang: Python
          source: |-
            import os
            from semilattice import Semilattice

            client = Semilattice(
                api_key=os.environ.get("SEMILATTICE_API_KEY"),  # This is the default and can be omitted
            )
            response = client.simulations.run(
                "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
            )
            print(response)
  /v1/simulations/{simulation_id}/share:
    post:
      tags:
        - Simulations
      summary: Make a simulation public
      description: Make a simulation publicly viewable and return its shareable URL.
      operationId: share_simulation_route_v1_simulations__simulation_id__share_post
      parameters:
        - name: simulation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Simulation Id
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/projects:
    get:
      tags:
        - Projects
      summary: List projects
      description: List projects visible to the caller, most recently active first.
      operationId: list_projects_route_v1_projects_get
      parameters:
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
        - Projects
      summary: Create a project
      description: |-
        Create a project. Create one first when you plan to run several related
        simulations, then pass its id as project_id when creating simulations.
      operationId: create_project_route_v1_projects_post
      parameters:
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectBody'
              default: {}
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/projects/{project_id}:
    get:
      tags:
        - Projects
      summary: Get a project
      description: |-
        Fetch a project with its rounds, simulations, and each round's current
        synthesis.
      operationId: get_project_route_v1_projects__project_id__get
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Project Id
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/context:
    get:
      tags:
        - Context
      summary: Get your context
      description: 'Return the caller''s saved context, or {has_context: false}.'
      operationId: get_context_route_v1_context_get
      parameters:
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateProjectBody:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Optional project name; defaults to 'New project'
      type: object
      title: CreateProjectBody
    CreateSimulationBody:
      properties:
        mode:
          type: string
          title: Mode
          description: '''research'' or ''journey'''
        goal:
          type: string
          title: Goal
          description: Goal id within the mode (from /v1/simulation-schema)
        inputs:
          additionalProperties: true
          type: object
          title: Inputs
          description: Answers keyed by the goal's input ids (from /v1/simulation-schema)
        user_model_ids:
          items:
            type: string
            format: uuid
          type: array
          title: User Model Ids
          description: One or more user-model ids to simulate against
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        project_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Project Id
          description: >-
            Optional project to add this simulation to; it joins the project's
            latest round (round 1 is created if none exists)
      type: object
      required:
        - mode
        - goal
        - user_model_ids
      title: CreateSimulationBody
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MoveSimulationBody:
      properties:
        project_id:
          type: string
          format: uuid
          title: Project Id
          description: >-
            Project to move this simulation into. Only allowed when the
            simulation has no project yet; it joins the project's latest round.
      type: object
      required:
        - project_id
      title: MoveSimulationBody
    SurveyQuestionIn:
      properties:
        question_text:
          type: string
          title: Question Text
        question_type:
          type: string
          title: Question Type
          default: single_choice
        answer_options:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Answer Options
        insight:
          anyOf:
            - type: string
            - type: 'null'
          title: Insight
        variable_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Variable Name
      type: object
      required:
        - question_text
      title: SurveyQuestionIn
    UpdatePlanBody:
      properties:
        question_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Question Text
        hypothesis_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Hypothesis Text
        survey_questions:
          anyOf:
            - items:
                $ref: '#/components/schemas/SurveyQuestionIn'
              type: array
            - type: 'null'
          title: Survey Questions
        journey_task:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Journey Task
      type: object
      title: UpdatePlanBody
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
