Skip to main content
POST
/
v1
/
workflows
/
spec
/
apply
from retab import Retab

client = Retab()

result = client.workflows.apply(yaml_definition)

print(result.workflow_id)
print(result.created)
print(result.summary.has_changes)
import { Retab } from "@retab/node";

const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

const result = await client.workflows.apply(yamlDefinition);

console.log(result.workflowId);
console.log(result.created);
console.log(result.summary.hasChanges);
package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	yamlDefinition := `apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
`
	result, err := client.Workflows.Apply(ctx, &retab.WorkflowsApplyParams{
		YamlDefinition: yamlDefinition,
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.WorkflowID)
	fmt.Println(result.Created)
	fmt.Println(result.Summary)
}
require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

result = client.workflows.apply(yaml_definition: yaml_definition)

puts result.workflow_id
puts result.created
puts result.summary.has_changes
use retab::models::DeclarativeWorkflowRequest;
use retab::resources::workflows::ApplyParams;
use retab::Retab;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Retab::new(std::env::var("RETAB_API_KEY")?);

    let yaml_definition = r#"apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
"#;
    let result = client
        .workflows()
        .apply(ApplyParams::new(DeclarativeWorkflowRequest::new(
            yaml_definition,
        )))
        .await?;

    println!("{}", result.workflow_id);
    println!("{}", result.created);
    if let Some(summary) = &result.summary {
        println!("{:?}", summary.has_changes);
    }
    Ok(())
}
<?php
require 'vendor/autoload.php';

use Retab\Client;

$client = new Client(apiKey: getenv('RETAB_API_KEY'));

$yamlDefinition = <<<'YAML'
apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
YAML;

$result = $client->workflows()->apply(
    yamlDefinition: $yamlDefinition,
);
print_r($result);
using Retab;
using RetabClient = Retab.Retab;

var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);

var yamlDefinition = """
apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
""";

var result = await client.Workflows.ApplyAsync(
    new WorkflowsApplyOptions { YamlDefinition = yamlDefinition }
);
Console.WriteLine(result);
import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.workflows().apply("metadata:\n  id: invoice-workflow\n", null, null);
    System.out.println(result);
  }
}
curl -X 'POST' \
  'https://api.retab.com/v1/workflows/spec/apply' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{
    "yaml_definition": "apiVersion: workflows.retab.com/v1alpha2\nkind: Workflow\nmetadata:\n  id: wf_invoice_demo\n  name: Invoice Workflow\nspec:\n  blocks:\n    start:\n      type: start_json\n      label: Input JSON\n      config:\n        json_schema:\n          type: object\n          required:\n            - value\n          properties:\n            value:\n              type: string\n  edges: []\n"
  }'
{
  "workflow_id": "wf_abc123",
  "created": true,
  "block_count": 2,
  "edge_count": 1,
  "diagnostics": {
    "issues": []
  },
  "format_version": "workflows-plan/v1",
  "summary": {
    "add": 0,
    "change": 0,
    "destroy": 0,
    "replace": 0,
    "noop": 1,
    "total": 0,
    "has_changes": false
  },
  "resource_changes": [],
  "rendered_plan": "No changes. Infrastructure is up-to-date."
}
Create a new workflow from a declarative workflow YAML spec. apply() creates a new workflow resource and writes the canonical draft graph represented by the YAML spec. It does not publish. Call the workflow publish method separately when the draft is ready to become the live version. If the YAML includes metadata.id, Retab treats it as source context, not as the target workflow id. To modify an existing workflow, use Apply Workflow Spec to Existing Workflow.
from retab import Retab

client = Retab()

result = client.workflows.apply(yaml_definition)

print(result.workflow_id)
print(result.created)
print(result.summary.has_changes)
import { Retab } from "@retab/node";

const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

const result = await client.workflows.apply(yamlDefinition);

console.log(result.workflowId);
console.log(result.created);
console.log(result.summary.hasChanges);
package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	yamlDefinition := `apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
`
	result, err := client.Workflows.Apply(ctx, &retab.WorkflowsApplyParams{
		YamlDefinition: yamlDefinition,
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.WorkflowID)
	fmt.Println(result.Created)
	fmt.Println(result.Summary)
}
require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

result = client.workflows.apply(yaml_definition: yaml_definition)

puts result.workflow_id
puts result.created
puts result.summary.has_changes
use retab::models::DeclarativeWorkflowRequest;
use retab::resources::workflows::ApplyParams;
use retab::Retab;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Retab::new(std::env::var("RETAB_API_KEY")?);

    let yaml_definition = r#"apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
"#;
    let result = client
        .workflows()
        .apply(ApplyParams::new(DeclarativeWorkflowRequest::new(
            yaml_definition,
        )))
        .await?;

    println!("{}", result.workflow_id);
    println!("{}", result.created);
    if let Some(summary) = &result.summary {
        println!("{:?}", summary.has_changes);
    }
    Ok(())
}
<?php
require 'vendor/autoload.php';

use Retab\Client;

$client = new Client(apiKey: getenv('RETAB_API_KEY'));

$yamlDefinition = <<<'YAML'
apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
YAML;

$result = $client->workflows()->apply(
    yamlDefinition: $yamlDefinition,
);
print_r($result);
using Retab;
using RetabClient = Retab.Retab;

var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);

var yamlDefinition = """
apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
""";

var result = await client.Workflows.ApplyAsync(
    new WorkflowsApplyOptions { YamlDefinition = yamlDefinition }
);
Console.WriteLine(result);
import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.workflows().apply("metadata:\n  id: invoice-workflow\n", null, null);
    System.out.println(result);
  }
}
curl -X 'POST' \
  'https://api.retab.com/v1/workflows/spec/apply' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{
    "yaml_definition": "apiVersion: workflows.retab.com/v1alpha2\nkind: Workflow\nmetadata:\n  id: wf_invoice_demo\n  name: Invoice Workflow\nspec:\n  blocks:\n    start:\n      type: start_json\n      label: Input JSON\n      config:\n        json_schema:\n          type: object\n          required:\n            - value\n          properties:\n            value:\n              type: string\n  edges: []\n"
  }'
{
  "workflow_id": "wf_abc123",
  "created": true,
  "block_count": 2,
  "edge_count": 1,
  "diagnostics": {
    "issues": []
  },
  "format_version": "workflows-plan/v1",
  "summary": {
    "add": 0,
    "change": 0,
    "destroy": 0,
    "replace": 0,
    "noop": 1,
    "total": 0,
    "has_changes": false
  },
  "resource_changes": [],
  "rendered_plan": "No changes. Infrastructure is up-to-date."
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Body carrying a workflow's full YAML definition for validate, plan, apply, or export.

yaml_definition
string
required

Workflow YAML definition

project_id
string | null

Project that should own a workflow created from this spec. Required when applying a spec that creates a new workflow.

Response

Successful Response

The outcome of applying a workflow YAML definition: whether the workflow was created, the changes made, and a rendered_plan.

workflow_id
string
required
action
enum<string>
required
Available options:
create,
update,
noop
created
boolean
required
block_count
integer
required
edge_count
integer
required
diagnostics
Diagnostics · object
required
format_version
string
default:workflows-plan/v1
summary
DeclarativePlanSummary · object
resource_changes
DeclarativePlanResourceChange · object[]
rendered_plan
string
default:No changes. Workflow spec is up to date.