> ## Documentation Index > Fetch the complete documentation index at: https://otoyinc.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create Job Recipe ## OpenAPI ````yaml https://api.dispersed.com/openapi.json post /v1/job-recipes openapi: 3.1.0 info: title: Dispersed API version: 1.0.0 servers: - url: https://api.dispersed.com security: [] paths: /v1/job-recipes: post: tags: - Job Recipes summary: Create Job Recipe requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 description: type: string maxLength: 500 visibility: type: string enum: - ARCHIVED - PRIVATE - PUBLIC - UNLISTED default: PRIVATE quickstart_md: type: string maxLength: 10000 description: Markdown content for the quickstart guide input_schema: type: array items: type: object properties: key: type: string description: >- Path in parameters where value is set (e.g., "sshkey", "env.API_KEY") type: type: string enum: - container_access_token - number - select - sshkey - text - textarea description: Input field type label: type: string description: Display label for the field description: type: string description: Help text displayed below the field required: type: boolean description: Whether this field must be provided placeholder: type: string description: Placeholder text for the input default_value: type: string description: Default value if user doesn't provide one options: type: array items: type: object properties: label: type: string value: type: string required: - label - value description: Options for 'select' type fields required: - key - type - label - required description: >- Schema defining required user inputs when cooking this recipe payload: type: object properties: title: type: string description: type: - string - 'null' task: type: string enum: - BATCH - PERSISTENT parameters: type: object properties: parameters: type: object properties: allowed_ips: type: array items: type: string description: >- Array of IPs allowed to access the container (if any). Accepts comma-separated string or array. If not specified, the container is accessible from any IP address. env: type: object additionalProperties: type: string description: >- Key-value pairs for container environment variables. host: type: string description: >- Custom registry host. If not specified, the default Docker Hub registry is used. Only applicable when using `image`. image: type: string minLength: 1 description: >- The Docker image to use for the container (e.g., "nginx", "myregistry/myimage"). Mutually exclusive with `imagesrc` - provide one or the other. imagesrc: type: string format: uri description: >- Signed HTTPS URL to download a Docker Image Archive (.tar file). Mutually exclusive with `image` - provide one or the other. When using imagesrc, `tag` is not applicable. ports: type: array items: type: number description: >- Array of ports to expose from the container (if any). If not specified, no ports are exposed. secret: type: string description: >- Secret for private registry authentication (if any). Required if the image is hosted on a private registry. Only applicable when using `image`. sshkey: type: string description: >- SSH public key to be added to the container for SSH access (if any). This public key will be passed to the container as `SSH_PUBKEY` environment variable. You must configure your container `~/.ssh/authorized_keys` to allow access. tag: type: string description: >- The tag of the Docker image to use. If not specified, defaults to "latest" on creation. Only applicable when using `image`, not `imagesrc`. user: type: string description: >- Username for private registry authentication (if any). Required if the image is hosted on a private registry. Only applicable when using `image`. volumes: type: array items: type: object properties: image: type: string mount: type: string registry: type: string secret: type: string tag: type: string user: type: string description: >- Array of volume definitions to mount into the container (if any). Each volume can optionally specify an image, mount point, registry, tag, user, and secret for private registry authentication. type: type: string enum: - docker required: - parameters - type min_vram_gb: type: number description: The minimum amount of VRAM in GB required for the Job. min_ram_gb: type: number description: The minimum amount of RAM in GB required for the Job. min_storage_gb: type: number description: >- The minimum amount of storage in GB required for the Job. max_timeout_assign_ms: type: - number - 'null' description: >- The maximum time in milliseconds to wait for the the JobRun to be assigned to a Node. Default: 5 minutes. max_timeout_run_ms: type: - number - 'null' description: The maximum time in milliseconds to execute the JobRun. max_timeout_start_ms: type: - number - 'null' description: >- The maximum time in milliseconds to wait for the the Node to finish preparing the assigned JobRun. Default: 5 minutes. cpu_count: type: - number - 'null' description: The number of CPU cores requested for the Job. example: 4 gpu_count: type: - number - 'null' description: The number of GPUs requested for the Job. example: 1 gpu_name: type: - string - 'null' description: (Optional) The name of the GPU to use for the Job. example: RTX 3090 gpu_registry_uuid: type: - string - 'null' description: >- (Optional) UUID of a GPU from the GpuRegistry for exact GPU targeting. example: 01234567-89ab-cdef-0123-456789abcdef image_size_bytes: type: - number - 'null' description: >- (Optional) The compressed Docker image size in bytes (from registry manifest). example: 2147483648 max_node_count: type: - number - 'null' description: The maximum number of Nodes to use for the Job. max_retry_count: type: - number - 'null' description: The maximum number of retries for the Job. allowed_region_codes: type: array items: $ref: '#/components/schemas/RegionCode' default: [] description: Allowed region codes for this Job. required: - title - task - parameters - min_vram_gb - min_ram_gb - min_storage_gb - cpu_count - gpu_count thumbnail_url: type: string format: uri description: URL to a thumbnail image for the recipe card is_official: type: boolean default: false required: - name - payload responses: '201': description: Job recipe created successfully (fields filtered by role) content: application/json: schema: $ref: '#/components/schemas/JobRecipeResponseFull' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: RegionCode: type: - string - 'null' enum: - ca-central-1 - ca-west-1 - mx-central-1 - sa-east-1 - us-east-1 - us-east-2 - us-west-1 - us-west-2 - eu-central-1 - eu-central-2 - eu-north-1 - eu-south-1 - eu-south-2 - eu-west-1 - eu-west-2 - eu-west-3 - ap-east-1 - ap-east-2 - ap-northeast-1 - ap-northeast-2 - ap-northeast-3 - ap-south-1 - ap-south-2 - ap-southeast-1 - ap-southeast-2 - ap-southeast-3 - ap-southeast-4 - ap-southeast-5 - ap-southeast-6 - ap-southeast-7 - cn-north-1 - cn-northwest-1 - af-south-1 - il-central-1 - me-central-1 - me-south-1 - null default: null description: Coarse geographic-network region identifier (AWS-style naming). example: us-west-2 JobRecipeResponseFull: type: object properties: uuid: type: - string - 'null' object: type: string enum: - job_recipe created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time name: type: string description: type: - string - 'null' visibility: type: string enum: - ARCHIVED - PRIVATE - PUBLIC - UNLISTED quickstart_md: type: - string - 'null' input_schema: type: - array - 'null' items: type: object properties: key: type: string description: >- Path in parameters where value is set (e.g., "sshkey", "env.API_KEY") type: type: string enum: - container_access_token - number - select - sshkey - text - textarea description: Input field type label: type: string description: Display label for the field description: type: string description: Help text displayed below the field required: type: boolean description: Whether this field must be provided placeholder: type: string description: Placeholder text for the input default_value: type: string description: Default value if user doesn't provide one options: type: array items: type: object properties: label: type: string value: type: string required: - label - value description: Options for 'select' type fields required: - key - type - label - required payload: type: object properties: title: type: string description: type: - string - 'null' task: type: string enum: - BATCH - PERSISTENT parameters: type: object properties: parameters: type: object properties: allowed_ips: type: array items: type: string description: >- Array of IPs allowed to access the container (if any). Accepts comma-separated string or array. If not specified, the container is accessible from any IP address. env: type: object additionalProperties: type: string description: Key-value pairs for container environment variables. host: type: string description: >- Custom registry host. If not specified, the default Docker Hub registry is used. Only applicable when using `image`. image: type: string minLength: 1 description: >- The Docker image to use for the container (e.g., "nginx", "myregistry/myimage"). Mutually exclusive with `imagesrc` - provide one or the other. imagesrc: type: string format: uri description: >- Signed HTTPS URL to download a Docker Image Archive (.tar file). Mutually exclusive with `image` - provide one or the other. When using imagesrc, `tag` is not applicable. ports: type: array items: type: number description: >- Array of ports to expose from the container (if any). If not specified, no ports are exposed. secret: type: string description: >- Secret for private registry authentication (if any). Required if the image is hosted on a private registry. Only applicable when using `image`. sshkey: type: string description: >- SSH public key to be added to the container for SSH access (if any). This public key will be passed to the container as `SSH_PUBKEY` environment variable. You must configure your container `~/.ssh/authorized_keys` to allow access. tag: type: string description: >- The tag of the Docker image to use. If not specified, defaults to "latest" on creation. Only applicable when using `image`, not `imagesrc`. user: type: string description: >- Username for private registry authentication (if any). Required if the image is hosted on a private registry. Only applicable when using `image`. volumes: type: array items: type: object properties: image: type: string mount: type: string registry: type: string secret: type: string tag: type: string user: type: string description: >- Array of volume definitions to mount into the container (if any). Each volume can optionally specify an image, mount point, registry, tag, user, and secret for private registry authentication. type: type: string enum: - docker required: - parameters - type min_vram_gb: type: number description: The minimum amount of VRAM in GB required for the Job. min_ram_gb: type: number description: The minimum amount of RAM in GB required for the Job. min_storage_gb: type: number description: The minimum amount of storage in GB required for the Job. max_timeout_assign_ms: type: - number - 'null' description: >- The maximum time in milliseconds to wait for the the JobRun to be assigned to a Node. Default: 5 minutes. max_timeout_run_ms: type: - number - 'null' description: The maximum time in milliseconds to execute the JobRun. max_timeout_start_ms: type: - number - 'null' description: >- The maximum time in milliseconds to wait for the the Node to finish preparing the assigned JobRun. Default: 5 minutes. cpu_count: type: - number - 'null' description: The number of CPU cores requested for the Job. example: 4 gpu_count: type: - number - 'null' description: The number of GPUs requested for the Job. example: 1 gpu_name: type: - string - 'null' description: (Optional) The name of the GPU to use for the Job. example: RTX 3090 gpu_registry_uuid: type: - string - 'null' description: >- (Optional) UUID of a GPU from the GpuRegistry for exact GPU targeting. example: 01234567-89ab-cdef-0123-456789abcdef image_size_bytes: type: - number - 'null' description: >- (Optional) The compressed Docker image size in bytes (from registry manifest). example: 2147483648 max_node_count: type: - number - 'null' description: The maximum number of Nodes to use for the Job. max_retry_count: type: - number - 'null' description: The maximum number of retries for the Job. allowed_region_codes: type: array items: $ref: '#/components/schemas/RegionCode' default: [] description: Allowed region codes for this Job. required: - title - task - parameters - min_vram_gb - min_ram_gb - min_storage_gb - cpu_count - gpu_count is_official: type: boolean thumbnail_url: type: - string - 'null' format: uri is_owner: type: boolean forked_from_recipe_uuid: type: - string - 'null' last_used_at: type: - string - 'null' format: date-time created_by_account_uuid: type: - string - 'null' created_by_account: type: - object - 'null' properties: uuid: type: - string - 'null' email: type: - string - 'null' usage_count: type: number fork_count: type: number required: - object - created_at - updated_at - name - description - visibility - payload - is_official - last_used_at - usage_count - fork_count ErrorResponse: type: object properties: error: $ref: '#/components/schemas/Error' required: - error Error: type: object properties: code: type: string details: type: array items: type: object properties: code: type: string expected: type: string input: type: string keys: type: array items: type: string message: type: string path: type: array items: anyOf: - type: string - type: number required: - message - path default: [] message: type: string status: type: number timestamp: type: string required: - code - message - status - timestamp ````