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

# Start a run

> Starts a model on an input and returns at once with a polling_url. Inputs are checked against the model's task schema before anything is charged; a refusal names the field.



## OpenAPI

````yaml /openapi.json post /runs
openapi: 3.1.0
info:
  title: Nemonist API
  version: 1.0.0
  description: >-
    OpenRouter-compatible API with durable per-workspace memory. Point any
    OpenRouter client at https://nemonist.com/api/v1 with a Nemonist key
    (sk-nm-...). Chat completions, Responses and Messages requests from a
    workspace carrying a .nemonist/key get its memory; every other request is
    answered as OpenRouter would.
  contact:
    name: Nemonist
    url: https://nemonist.com
servers:
  - url: https://nemonist.com/api/v1
    description: Production
security:
  - apiKey: []
tags:
  - description: API key management endpoints
    name: API Keys
  - description: Analytics and usage endpoints
    name: Analytics
  - description: Anthropic Messages endpoints
    name: Anthropic Messages
  - description: BYOK endpoints
    name: BYOK
  - description: Benchmarks endpoints
    name: Benchmarks
  - description: Chat completion endpoints
    name: Chat
  - description: Credit management endpoints
    name: Credits
  - description: >-
      Public OpenRouter usage datasets. Data returned by these endpoints is
      licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/):
      reuse and republish it, including commercially, with attribution to
      OpenRouter.
    name: Datasets
  - description: Text embedding endpoints
    name: Embeddings
  - description: Endpoint information
    name: Endpoints
  - name: Folders
    description: >-
      Your memory folders, over your account's API key: read, export, upload,
      and manage keys.
  - description: Generation history endpoints
    name: Generations
  - description: Guardrails endpoints
    name: Guardrails
  - description: Images endpoints
    name: Images
  - name: Memory
    description: Nemonist's per-workspace memory.
  - name: Model runs
    description: Run models (physics and others) on inputs; one contract for every model
  - description: Model information endpoints
    name: Models
  - description: OAuth authentication endpoints
    name: OAuth
  - description: Organization endpoints
    name: Organization
  - description: Private Endpoints endpoints
    name: Private Endpoints
  - description: Provider information endpoints
    name: Providers
  - description: Rerank endpoints
    name: Rerank
  - description: OpenAI-compatible Responses API endpoints
    name: Responses
  - description: Speech-to-text endpoints
    name: STT
    x-displayName: Transcriptions
  - description: >-
      System One endpoints for models such as Jev, compatible with the TypeSafe
      SDKs. See https://openrouter.ai/docs/guides/community/typesafe-sdk.
    name: SystemOne
    x-displayName: System One
  - description: Text-to-speech endpoints
    name: TTS
    x-displayName: Speech
  - description: Video Generation endpoints
    name: Video Generation
  - description: Workspaces endpoints
    name: Workspaces
  - name: beta.responses
    description: >-
      Deprecated alias of responses. Use responses instead; scheduled for
      removal (sunset date TBD).
paths:
  /runs:
    post:
      tags:
        - Model runs
      summary: Start a run
      description: >-
        Starts a model on an input and returns at once with a polling_url.
        Inputs are checked against the model's task schema before anything is
        charged; a refusal names the field.
      operationId: createRun
      parameters:
        - name: folder
          in: query
          required: false
          schema:
            type: string
          description: A folder id (fld_...) you own; default your key's default folder.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              properties:
                model:
                  type: string
                  description: A model id from GET /runs/models
                input:
                  oneOf:
                    - $ref: '#/components/schemas/RunInput_flow'
                  description: >-
                    The model's task input; GET /runs/models shows which task
                    each model takes.
                reason:
                  type: string
                  description: Why, kept with the run
      responses:
        '200':
          description: The run, pending.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
                description: >-
                  A run: id, status (pending, in_progress, completed, failed),
                  model, task, polling_url, held_usd, and once ended seconds,
                  charged_usd, conclusion (success, failure, cancelled,
                  timed_out, out_of_memory, startup_failure), result (the
                  model's result.json inline), unsigned_urls and outputs.
        '400':
          description: The input does not match the model's task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NemonistError'
        '401':
          description: Missing or invalid key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NemonistError'
        '402':
          description: Not enough credits for the run's hold.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NemonistError'
        '500':
          description: 'Nemonist: an internal error answered this request; retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NemonistError'
        '503':
          description: 'Nemonist: the service is temporarily unavailable; retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NemonistError'
components:
  schemas:
    RunInput_flow:
      type: object
      additionalProperties: false
      required:
        - setup
        - fluid
      properties:
        setup:
          oneOf:
            - type: object
              additionalProperties: false
              required:
                - kind
                - lid_velocity
              description: >-
                Flow inside a closed box, driven by its top wall (y = size[1])
                sliding in its own plane. The box spans [0, size] from the
                origin.
              properties:
                kind:
                  const: lid-driven-box
                  description: always lid-driven-box
                size:
                  type: array
                  items:
                    type: number
                  minItems: 3
                  maxItems: 3
                  default:
                    - 1
                    - 1
                    - 0.1
                  description: metres; give dimensions 2 for a planar flow
                dimensions:
                  enum:
                    - 2
                    - 3
                  default: 2
                  description: '2: planar flow in x-y; 3: full 3D'
                lid_velocity:
                  type: array
                  items:
                    type: number
                  minItems: 3
                  maxItems: 3
                  description: m/s, in the lid's plane (y component 0)
            - type: object
              additionalProperties: false
              required:
                - kind
                - surface
                - freestream
              description: >-
                Flow around a body in open air or water. The body is a closed
                surface (STL) you upload; the model sizes the surrounding domain
                itself.
              properties:
                kind:
                  const: external
                  description: always external
                surface:
                  type: string
                  format: file
                  description: an uploaded STL file (ASCII or binary)
                units:
                  enum:
                    - m
                    - mm
                    - cm
                    - in
                  default: m
                  description: the STL's length unit
                freestream:
                  type: array
                  items:
                    type: number
                  minItems: 3
                  maxItems: 3
                  description: m/s, the undisturbed velocity far from the body
                reference_area:
                  type: number
                  exclusiveMinimum: 0
                  description: m^2, for force coefficients; default the body's frontal area
                reference_length:
                  type: number
                  exclusiveMinimum: 0
                  description: >-
                    m, for moment coefficients and the Reynolds number; default
                    the body's length along the freestream
          description: the geometry and boundary conditions
        fluid:
          type: object
          additionalProperties: false
          required:
            - kinematic_viscosity
          description: the fluid's properties
          properties:
            kinematic_viscosity:
              type: number
              exclusiveMinimum: 0
              description: m^2/s
            density:
              type: number
              exclusiveMinimum: 0
              default: 1
              description: kg/m^3; scales pressures and forces
        turbulence:
          enum:
            - auto
            - laminar
            - rans
          default: auto
          description: >-
            auto picks laminar or RANS from the Reynolds number; the result says
            which
        fidelity:
          enum:
            - draft
            - standard
            - fine
          default: standard
          description: resolution and convergence effort; cost grows with it
        outputs:
          type: object
          additionalProperties: false
          default: {}
          description: what the result holds besides the scalars
          properties:
            fields:
              type: boolean
              default: true
              description: velocity and pressure fields (VTK)
            forces:
              type: boolean
              default: true
              description: force and coefficients on walls/body
            probes:
              type: array
              items:
                type: array
                items:
                  type: number
                minItems: 3
                maxItems: 3
                description: x, y, z in metres
              maxItems: 1000
              default: []
              description: points where velocity and pressure are sampled
            lines:
              type: array
              maxItems: 20
              default: []
              items:
                type: object
                additionalProperties: false
                required:
                  - from
                  - to
                properties:
                  from:
                    type: array
                    items:
                      type: number
                    minItems: 3
                    maxItems: 3
                    description: x, y, z in metres
                  to:
                    type: array
                    items:
                      type: number
                    minItems: 3
                    maxItems: 3
                    description: x, y, z in metres
                  points:
                    type: integer
                    minimum: 2
                    maximum: 1000
                    default: 101
                    description: how many evenly spaced samples
                  name:
                    type: string
                    description: a label for the line in the result
              description: straight lines sampled at evenly spaced points
      description: >-
        Steady incompressible flow (SI units). Pressure p is kinematic times
        density (Pa).
    NemonistError:
      type: object
      description: An error answer.
      required:
        - error
      properties:
        error:
          type: object
          description: What went wrong.
          required:
            - message
          properties:
            code:
              type:
                - integer
                - string
              description: HTTP status or a short error code.
            type:
              type: string
              description: Error kind, such as proxy_error.
            message:
              type: string
              description: Human-readable error message.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        A Nemonist key (sk-nm-...) as a bearer token in the Authorization
        header.

````

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