Freestyle Execute API

openapi: 3.1.0
info:
  title: Freestyle Execute API
  version: 0.1.0
  description: "Run user-supplied or AI-generated JavaScript/TypeScript code on demand \u2014 ephemeral execution, list runs,\
    \ fetch saved output, with node-module caching."
  contact:
    name: Ben
    email: ben@freestyle.sh
  license:
    name: Closed Source
servers:
- url: https://api.freestyle.sh
  description: Production
tags:
- name: Execute
  description: APIs for running code. Send the code using the [execute](#tag/execute/POST/execute/v1/execute) endpoint, and
    you'll get the output back. Works with any TypeScript or JavaScript code + handles any node modules and environment variables
    you want.
paths:
  /execute/v1/deployments:
    get:
      tags:
      - Execute
      summary: List Execute Runs
      description: List execute runs.
      operationId: handle_list_execute_runs
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
      - name: offset
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                required:
                - entries
                - total
                - offset
                properties:
                  entries:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExecuteLogEntry'
                  total:
                    type: integer
                    format: int64
                    minimum: 0
                  offset:
                    type: integer
                    format: int64
                    minimum: 0
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
  /execute/v1/deployments/{deployment}:
    get:
      tags:
      - Execute
      summary: Get Information on Execute Run
      description: Get information on execute run
      operationId: handle_get_execute_run
      parameters:
      - name: deployment
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - metadata
                properties:
                  metadata:
                    $ref: '#/components/schemas/ExecuteLogEntry'
                  code:
                    oneOf:
                    - type: 'null'
                    - $ref: '#/components/schemas/ExecuteRunInfo'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                type: object
                description: Unauthorized access
                required:
                - message
                properties:
                  message:
                    type: string
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                description: Not found
                required:
                - message
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                description: Internal server error
                required:
                - message
                properties:
                  message:
                    type: string
  /execute/v1/deployments/{deployment}/output:
    get:
      tags:
      - Execute
      summary: Get Saved Output for an Execute Run
      description: Get saved output for execute run
      operationId: handle_get_execute_run_output
      parameters:
      - name: deployment
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - logs
                properties:
                  status:
                    type: string
                  result: {}
                  error:
                    type:
                    - string
                    - 'null'
                  logs:
                    type: array
                    items:
                      $ref: '#/components/schemas/FreestyleJavaScriptLog'
        '401':
          description: ''
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
  /execute/v3/script:
    post:
      tags:
      - Execute
      summary: Execute Code
      description: Send a TypeScript or JavaScript module, get the result
      operationId: handle_execute_script_v3
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FreestyleExecuteScriptParams'
        required: true
      responses:
        '200':
          description: Script executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteScriptSuccess'
        '403':
          description: 'Error: ExecuteLimitExceeded'
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    description: Error code in SCREAMING_SNAKE_CASE
                  message:
                    type: string
                    description: Human-readable error message
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    ExecuteRunInfo:
      type: object
      required:
      - code
      - nodeModules
      properties:
        code:
          type: string
        nodeModules:
          type: object
          additionalProperties:
            type: string
          propertyNames:
            type: string
    FreestyleNetworkPermission:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/NetworkPermissionData'
        - type: object
          required:
          - action
          properties:
            action:
              type: string
              enum:
              - allow
      - allOf:
        - $ref: '#/components/schemas/NetworkPermissionData'
        - type: object
          required:
          - action
          properties:
            action:
              type: string
              enum:
              - deny
    ExecuteScriptSuccess:
      type: object
      description: Success result from script execution
      required:
      - result
      - logs
      properties:
        result: {}
        logs:
          type: array
          items:
            $ref: '#/components/schemas/JavascriptLog'
    JavascriptLog:
      oneOf:
      - type: object
        required:
        - message
        - type
        properties:
          message:
            type: string
          callstack:
            type:
            - string
            - 'null'
          type:
            type: string
            enum:
            - log
      - type: object
        required:
        - message
        - type
        properties:
          message:
            type: string
          callstack:
            type:
            - string
            - 'null'
          type:
            type: string
            enum:
            - error
    FreestyleJavaScriptLog:
      type: object
      required:
      - message
      - type
      properties:
        message:
          type: string
          description: The log message
          example: I'm a log!
        type:
          type: string
          description: The log level
          example: log
    EgressDenyRules:
      type: object
      properties:
        ips:
          type:
          - object
          - 'null'
          description: 'Blacklist of IPs. These override allow rules.

            CIDR notation supported.'
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/EgressIpConfig'
          propertyNames:
            type: string
    Behavior:
      type: string
      default: exact
      enum:
      - regex
      - exact
    EgressTransform:
      type: object
      properties:
        headers:
          type:
          - object
          - 'null'
          description: Headers to set on outgoing requests
          additionalProperties:
            type: string
          propertyNames:
            type: string
    EgressAllowRules:
      type: object
      properties:
        domains:
          type:
          - object
          - 'null'
          description: 'Whitelist of domains. Empty object means no domains allowed.

            "*" means allow all domains.

            Domain name maps to a list of transformations (currently just headers).'
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/EgressDomainConfig'
          propertyNames:
            type: string
        ips:
          type:
          - object
          - 'null'
          description: 'Whitelist of IPs. Empty object means no IPs allowed.

            CIDR notation supported (e.g., "173.194.0.0/16").

            IPs are allowed on any port/protocol.'
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/EgressIpConfig'
          propertyNames:
            type: string
    EgressConfig:
      type: object
      properties:
        allow:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/EgressAllowRules'
            description: Allow rules for egress traffic
        deny:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/EgressDenyRules'
            description: Deny rules for egress traffic (evaluated after allow)
    FreestyleExecuteScriptParams:
      type: object
      required:
      - script
      properties:
        script:
          type: string
          description: The JavaScript or TypeScript script to execute
          example: "export default () => {\n  // get the value of the factorials of the numbers from 1 to 10 combined\n  const\
            \ a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];\n\n  function factorial(n) {\n    if (n === 0) {\n      return 1;\n   \
            \ }\n    return n * factorial(n - 1);\n  }\n\n  const b = a.map(factorial);\n\n  return b.reduce((a, b) => a +\
            \ b);\n};\n"
        executionId:
          type:
          - string
          - 'null'
          format: uuid
          description: Optional execution ID for callers that need deterministic run correlation.
        config:
          $ref: '#/components/schemas/FreestyleExecuteScriptParamsConfiguration'
    NetworkPermissionData:
      type: object
      required:
      - query
      properties:
        query:
          type: string
        behavior:
          $ref: '#/components/schemas/Behavior'
    ExecuteLogEntry:
      type: object
      required:
      - deployment
      - accountId
      - provisionedAt
      - state
      - envVars
      properties:
        deployment:
          type: string
          format: uuid
        accountId:
          type: string
          format: uuid
        provisionedAt:
          type: string
          format: date-time
        startedAt:
          type:
          - string
          - 'null'
          format: date-time
        duration:
          type:
          - string
          - 'null'
        state:
          $ref: '#/components/schemas/ExecuteRunState'
        envVars:
          type: object
          additionalProperties:
            type: string
          propertyNames:
            type: string
    EgressDomainConfig:
      type: object
      properties:
        transform:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/EgressTransform'
          description: Transformations to apply to requests to this domain
    FreestyleExecuteScriptParamsConfiguration:
      type: object
      properties:
        envVars:
          type: object
          description: The environment variables to set for the script
          default: {}
          additionalProperties:
            type: string
          propertyNames:
            type: string
          example:
            RESEND_API_KEY: re_123456789
        nodeModules:
          type: object
          description: The node modules to install for the script
          default: {}
          additionalProperties:
            type: string
          propertyNames:
            type: string
          example:
            resend: 4.0.1
        inferNodeModules:
          type: boolean
          description: If true, Freestyle will best-effort infer npm packages from script imports.
          default: false
        tags:
          type: array
          items:
            type: string
          description: Tags for you to organize your scripts, useful for tracking what you're running
          example:
          - email
          default: []
        timeout:
          type:
          - integer
          - 'null'
          format: int32
          description: The script timeout
          default: null
          minimum: 0
        peerDependencyResolution:
          type: boolean
          description: If false, we'll not resolve peer dependencies for the packages given, this can speed up execute performance,
            but will break packages with peers unless the peers are manually specified.
          default: true
        networkPermissions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FreestyleNetworkPermission'
          default: null
        customHeaders:
          type: object
          description: These headers will be added to every fetch request made through the script
          default: {}
          additionalProperties:
            type: string
          propertyNames:
            type: string
        proxy:
          type:
          - string
          - 'null'
          description: Proxy all outgoing requests through this URL
          default: null
          example: https://aproxyyouown.com
        egress:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/EgressConfig'
            description: Egress control configuration for outbound requests (domains, IPs, transformations)
          default: null
        zeroRetention:
          type:
          - boolean
          - 'null'
          description: If true, Freestyle will not retain the code, any logs, environment variables, or results from this
            execution.
          default: null
          example: false
    ExecuteRunState:
      type: string
      enum:
      - starting
      - running
      - complete
    EgressIpConfig:
      type: object
      properties:
        transform:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/EgressTransform'
          description: Transformations to apply to requests to this IP
security:
- bearerAuth: []