---
title: "Compile and store a shader"
method: POST
path: "/v1/shaders"
tags: ["shaders"]
---

# Compile and store a shader

`POST /v1/shaders`

## Request

- Base URL: `https://api.framelane.io`
- URL: `https://api.framelane.io/v1/shaders`
- Auth: HTTP bearer

Compile an SkSL source into the GLSL and WGSL variants the render engines run, and store it. Use the returned `id` as `effects[].shader.id` on a video, image, shape, frame or instance; `POST /v1/shaders/{id}/probe` renders one frame of it first.

## Request body

- ShaderCreate: ``POST /v1/shaders``: compile an SkSL source and store it.
  - `name` string, required: A label, carried into renders as the entry's name.
  - `lang` 'sksl': The source language; SkSL is the only one.
  - `source` string, required: The SkSL body: `half4 main(float2 uv)` (uv 0 to 1 from the top-left), or Jitter's `half4 jitterMain(float2 uv)`. No `uniform` declarations: uniforms come from the prelude and `params`.
  - `jitter` boolean, nullable: Compile in Jitter's dialect. Omitted: when the source defines `jitterMain`.
  - `params` ShaderParamSpec[]: The params the source reads, in order.
    - `name` string, required: A letter, then letters, digits and single underscores; not a prelude name (`time` is taken by `u_time`). The shader reads it as `u_<name>`.
    - `type` 'float' | 'color' | 'vec2', required: `float`, `color` (straight-alpha RGBA) or `vec2`.
    - `default` union: Its value where an effect does not set it. Omitted: 0, transparent black or [0, 0].
      - number
      - string
      - number[]
    - `min` number, nullable: Lowest value an effect may set (a vec2's each component).
    - `max` number, nullable: Highest value an effect may set (a vec2's each component).

## Response `201`

Successful Response

- ShaderOut: A stored shader. `variants` and `source` come back with `?view=full` only.
  - `id` string, required: Its id, for `effects[].shader.id`.
  - `name` string, required
  - `lang` string, required
  - `hash` string, required: SHA-256 of "sksl\n" + source, 64 lowercase hex digits: the entry's identity.
  - `jitter` boolean, required: Compiled in Jitter's dialect.
  - `status` 'compiled' | 'failed', required: `failed` shaders cannot render; `errors` says why.
  - `errors` ShaderCompileError[]: The compiler's errors, with positions.
    - `line` integer, required: 1-based line in the source; 0 when the error is not in it (a param).
    - `col` integer, required: 1-based column in the source; 0 with line 0.
    - `message` string, required
  - `params` ShaderParamSpec[], required
    - `name` string, required: A letter, then letters, digits and single underscores; not a prelude name (`time` is taken by `u_time`). The shader reads it as `u_<name>`.
    - `type` 'float' | 'color' | 'vec2', required: `float`, `color` (straight-alpha RGBA) or `vec2`.
    - `default` union: Its value where an effect does not set it. Omitted: 0, transparent black or [0, 0].
      - number
      - string
      - number[]
    - `min` number, nullable: Lowest value an effect may set (a vec2's each component).
    - `max` number, nullable: Highest value an effect may set (a vec2's each component).
  - `variant_hashes` object: SHA-256 of each variant (`glsl330`, `glsles300`, `wgsl`), as the engines check them.
  - `shared` boolean, required: A shared shader every workspace can use, and none can delete.
  - `source` string, nullable: The SkSL source (`?view=full`).
  - `variants` object, nullable: The compiled variants' text (`?view=full`).
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `401`: Missing or invalid API key.
- `422`: `shader_compile_error`: the source did not compile (`details.errors` lists each error with its line and column; the failed shader is stored as `details.shader_id`), or `source_too_large`.
- `503`: `shader_compiler_unavailable`: no compiler on this deployment, or it timed out.

---

[API](https://skmtc.dev/framelane/apis/framelane-api.md) · [All operations](https://skmtc.dev/framelane/apis/framelane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/framelane/apis/framelane-api/revisions/a223001ca8e5?raw)