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

# Start a Team run from an optional skill and prompt, or a script

> Supply a skill, a prompt, or images for an agent run. Script-based runs are retired. Skill frontmatter selects VM, permission and model presets; omitted selections inherit team defaults. Resolved preset revisions and the skill commit are snapshotted before queueing. Default scopes, integrations and invocation destinations are bounded by the caller's effective access. Explicit unauthorized permissions fail. Explicit empty selections grant none.

Requires the runs:start scope.

Accepts a scoped bearer token, vendor-verified run identity, or interactive owner session.



## OpenAPI

````yaml /openapi.yaml post /api/v1/runs
openapi: 3.1.0
info:
  title: Factorize API
  version: 1.0.0
  description: >-
    Versioned Factorize REST API. See the hosted docs for examples and OAuth
    discovery.
  x-dashboard-auth: >-
    Access-token and authorized-client management and trace replay operations
    require an interactive owner session; all other operations accept a suitably
    scoped bearer token or owner session.
servers:
  - url: https://app.factorize.sh
security:
  - bearerAuth: []
paths:
  /api/v1/runs:
    post:
      tags:
        - runs
      summary: Start a Team run from an optional skill and prompt, or a script
      description: >-
        Supply a skill, a prompt, or images for an agent run. Script-based runs
        are retired. Skill frontmatter selects VM, permission and model presets;
        omitted selections inherit team defaults. Resolved preset revisions and
        the skill commit are snapshotted before queueing. Default scopes,
        integrations and invocation destinations are bounded by the caller's
        effective access. Explicit unauthorized permissions fail. Explicit empty
        selections grant none.


        Requires the runs:start scope.


        Accepts a scoped bearer token, vendor-verified run identity, or
        interactive owner session.
      operationId: post_api_v1_runs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vmPreset:
                  type: string
                  maxLength: 120
                  pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
                permissionPreset:
                  type: string
                  maxLength: 120
                  pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
                modelPreset:
                  type: string
                  maxLength: 120
                  pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
                attachments:
                  maxItems: 16
                  type: array
                  items:
                    type: object
                    properties:
                      artifactId:
                        type: string
                        format: uuid
                        pattern: >-
                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    required:
                      - artifactId
                    additionalProperties: false
                requiresVm:
                  type: boolean
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 50000
                script:
                  description: >-
                    Retired: returns scripts_retired. Use an agent skill to
                    execute code.
                  deprecated: true
                  type: string
                  minLength: 1
                  maxLength: 200000
                skill:
                  type: string
                  minLength: 1
                  maxLength: 64
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
                executionConfigId:
                  type: string
                  minLength: 1
                modelAccountId:
                  type: string
                  format: uuid
                  pattern: >-
                    ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                vmImage:
                  type: string
                  maxLength: 512
                  pattern: >-
                    ^(?:(?:(?:[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*\/)?[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*(?:\/[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*)*(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?(?:@sha256:[a-f0-9]{64})?))?$
                model:
                  type: string
                  maxLength: 120
                runScopes:
                  description: >-
                    Factorize application permissions to grant. Omission
                    inherits effective client permissions and an empty list
                    grants none.
                  maxItems: 13
                  type: array
                  items:
                    type: string
                    enum:
                      - team:read
                      - team:write
                      - triggers:read
                      - triggers:write
                      - runs:read
                      - runs:invoke
                      - runs:start
                      - runs:cancel
                      - runs:write
                      - integrations:read
                      - integrations:write
                      - skills:read
                      - skills:write
                integrationIds:
                  maxItems: 100
                  type: array
                  items:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                inputs:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties: {}
                idempotencyKey:
                  type: string
                  minLength: 1
                  maxLength: 200
              additionalProperties: false
      responses:
        '202':
          description: Accepted run
          content:
            application/json:
              schema:
                type: object
                properties:
                  runId:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  url:
                    type: string
                    format: uri
                  outcomeUri:
                    type: string
                  duplicate:
                    type: boolean
                required:
                  - runId
                  - url
                  - outcomeUri
                  - duplicate
                additionalProperties: false
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '415':
          $ref: '#/components/responses/Error415'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      security:
        - bearerAuth: []
        - vendorRunIdentity: []
          runIdentityHeader: []
        - cookieAuth: []
components:
  responses:
    Error400:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error401:
      description: Invalid or revoked credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error403:
      description: Missing scope or required owner session
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error404:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error409:
      description: Operation conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error415:
      description: Unsupported media type; use application/json
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error429:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error500:
      description: Internal error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error503:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2
    vendorRunIdentity:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Fresh vendor-signed exe.dev WIF or Fly Machine OIDC token matching the
        provisioned active run. Must be combined with X-Factorize-Run-Id; a
        vendor token alone grants no access.
    runIdentityHeader:
      type: apiKey
      in: header
      name: X-Factorize-Run-Id
      description: >-
        Provisioned run UUID. Used only to locate the immutable vendor/VM
        binding; this header is not a credential. Scopes and tenant come from
        the server-side run snapshot.
    cookieAuth:
      type: apiKey
      in: cookie
      name: factorize_session

````

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