Workflows

Workspaces

List Workspaces

post

Lists all Workspaces with Filtering and Sorting Options. Supports VCS Providers Integration.

Authorizations
Query parameters
pageintegerOptionalDefault: 0
pageSizeinteger · min: 1OptionalDefault: 25
Body
all ofOptional
Responses
200

List of Workspaces Retrieved Successfully

application/json
post
POST /v2/workspaces/search HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 614

{
  "projection": [
    "text"
  ],
  "searchValue": "text",
  "filters": {
    "workspaceName": [
      "production-infra"
    ],
    "repositories": [
      "org/repo-name"
    ],
    "ciTool": [
      "github-actions"
    ],
    "labels": [
      "text"
    ],
    "status": [
      "plan_success"
    ],
    "isManagedWorkflow": true,
    "vcsType": [
      "github"
    ],
    "$or": {
      "workspaceName": [
        "production-infra"
      ],
      "repositories": [
        "org/repo-name"
      ],
      "ciTool": [
        "github-actions"
      ],
      "labels": [
        "text"
      ],
      "status": [
        "plan_success"
      ],
      "isManagedWorkflow": true,
      "vcsType": [
        "github"
      ]
    }
  },
  "sort": {
    "lastRunTime": {
      "order": -1
    },
    "workspaceName": {
      "order": -1
    },
    "repository": {
      "order": -1
    },
    "terraformVersion": {
      "order": -1
    },
    "lastRunStatus": {
      "order": -1
    },
    "ciTool": {
      "order": -1
    }
  }
}
[
  {
    "id": "507f1f77bcf86cd799439011",
    "accountId": "507f1f77bcf86cd799439011",
    "createdAt": "2025-08-19T22:12:28.332Z",
    "updatedAt": "2025-08-19T22:12:28.332Z",
    "workspaceId": "507f1f77bcf86cd799439012",
    "workspaceName": "production-infra",
    "repo": "org/repo-name",
    "repoUrl": "https://github.com/org/repo-name",
    "vcsType": "github",
    "runnerType": "github-actions",
    "lastRunStatus": {
      "description": "text"
    },
    "lastApplyTime": "2025-08-19T22:12:28.332Z",
    "lastPlanTime": "2025-08-19T22:12:28.332Z",
    "lastRunTime": "2025-08-19T22:12:28.332Z",
    "iacType": "terraform",
    "iacTypeVersion": "1.0.11",
    "backendSummary": {
      "backendType": "s3",
      "backendConfig": {
        "bucket": "terraform-state",
        "key": "prod/terraform.tfstate"
      },
      "iacStackId": "stack-123",
      "managedResourceCount": 42
    },
    "labels": [
      "prod",
      "terraform"
    ],
    "runsCount": 5,
    "isWorkflowManaged": true,
    "guardrails": [
      "cost",
      "security"
    ]
  }
]

Delete a workspace

delete

Deletes a specific workspace and its associated data

Authorizations
Path parameters
workspaceIdstringRequired

Unique identifier of the workspace

Example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Responses
200

Workspace deleted successfully

application/json
delete
DELETE /v2/workspaces/{workspaceId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

{
  "status": 200,
  "data": {
    "message": "Workspace deleted successfully"
  }
}

Update Workspace Labels

put

Updates Labels for a specific Workspace

Authorizations
Path parameters
workspaceIdstringRequired

Unique identifier of the workspace

Example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Body
labelsstring[]Required

List of labels to assign to the workspace

Responses
200

Workspace Labels Updated Successfully

application/json
put
PUT /v2/workspaces/{workspaceId}/labels HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "labels": [
    "text"
  ]
}
{
  "id": "507f1f77bcf86cd799439015",
  "workspaceName": "production-infra",
  "labels": [
    "production",
    "terraform",
    "critical"
  ],
  "updatedAt": "2025-08-19T22:12:28.332Z"
}

List Workspace Runs

post

Lists all Runs for a specific Workspace

Authorizations
Path parameters
workspaceIdstringRequired

Unique identifier of the workspace

Example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Query parameters
pageintegerOptionalDefault: 0
pageSizeinteger · min: 1OptionalDefault: 25
Body
all ofOptional
Responses
200

List of Workspace Runs Retrieved Successfully

application/json
post
POST /v2/workspaces/{workspaceId}/runs/search HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 1366

{
  "projection": [
    "text"
  ],
  "searchValue": "text",
  "filters": {
    "runId": [
      "run-123456"
    ],
    "runName": [
      "Deploy to Production"
    ],
    "status": [
      "plan_success"
    ],
    "pullRequestUrl": [
      "https://github.com/org/repo/pull/123"
    ],
    "branch": [
      "main"
    ],
    "commitId": [
      "abc123def456"
    ],
    "ciTool": [
      "github-actions"
    ],
    "buildId": [
      "build-789012"
    ],
    "buildName": [
      "CI Build"
    ],
    "buildUrl": [
      "https://github.com/org/repo/actions/runs/789012"
    ],
    "vcsType": [
      "github"
    ],
    "repository": [
      "org/repo"
    ],
    "repositoryUrl": [
      "https://github.com/org/repo"
    ],
    "title": [
      "Update infrastructure for new feature"
    ],
    "createdAt": "2025-08-19T22:12:28.332Z",
    "updatedAt": "2025-08-19T22:12:28.332Z",
    "$or": {
      "runId": [
        "run-123456"
      ],
      "runName": [
        "Deploy to Production"
      ],
      "status": [
        "plan_success"
      ],
      "pullRequestUrl": [
        "https://github.com/org/repo/pull/123"
      ],
      "branch": [
        "main"
      ],
      "commitId": [
        "abc123def456"
      ],
      "ciTool": [
        "github-actions"
      ],
      "buildId": [
        "build-789012"
      ],
      "buildName": [
        "CI Build"
      ],
      "buildUrl": [
        "https://github.com/org/repo/actions/runs/789012"
      ],
      "vcsType": [
        "github"
      ],
      "repository": [
        "org/repo"
      ],
      "repositoryUrl": [
        "https://github.com/org/repo"
      ],
      "title": [
        "Update infrastructure for new feature"
      ],
      "createdAt": "2025-08-19T22:12:28.332Z",
      "updatedAt": "2025-08-19T22:12:28.332Z"
    }
  },
  "sort": {
    "updatedAt": {
      "order": -1
    },
    "title": {
      "order": -1
    },
    "commitId": {
      "order": -1
    },
    "branch": {
      "order": -1
    },
    "status": {
      "order": -1
    },
    "ciTool": {
      "order": -1
    },
    "vcsType": {
      "order": -1
    },
    "repository": {
      "order": -1
    }
  }
}
[
  {
    "id": "507f1f77bcf86cd799439011",
    "accountId": "507f1f77bcf86cd799439011",
    "createdAt": "2025-08-19T22:12:28.332Z",
    "updatedAt": "2025-08-19T22:12:28.332Z",
    "workspaceId": "507f1f77bcf86cd799439012",
    "workspaceName": "production-infra",
    "runId": "run-123456",
    "runName": "Deploy to Production",
    "status": "plan_success",
    "pullRequestId": "123",
    "pullRequestUrl": "https://github.com/org/repo/pull/123",
    "branch": "main",
    "commitId": "abc123def456",
    "commitUrl": "https://github.com/org/repo/commit/abc123def456",
    "runnerType": "github-actions",
    "buildId": "build-789012",
    "buildUrl": "https://github.com/org/repo/actions/runs/789012",
    "buildName": "CI Build",
    "vcsType": "github",
    "repo": "org/repo",
    "repoUrl": "https://github.com/org/repo",
    "ownerSummary": {
      "email": "[email protected]",
      "name": "John Doe",
      "initials": "JD",
      "customColor": "#00000F"
    },
    "title": "Update infrastructure for new feature",
    "terraformVersion": "1.0.11",
    "iacType": "terraform",
    "backendSummary": {
      "backendType": "s3",
      "backendConfig": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "iacStackId": "text",
      "managedResourceCount": 1
    },
    "planTaskId": "507f1f77bcf86cd799439013",
    "applyTaskId": "507f1f77bcf86cd799439014",
    "plan": [
      {
        "id": "507f1f77bcf86cd799439011",
        "accountId": "507f1f77bcf86cd799439011",
        "createdAt": "2025-08-19T22:12:28.332Z",
        "updatedAt": "2025-08-19T22:12:28.332Z",
        "contentKeys": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "status": "completed",
        "resultStatus": "success",
        "type": {
          "description": "text"
        },
        "guardrailsSummary": {
          "total": 10,
          "passed": 8,
          "failed": 2,
          "violations": [
            {
              "id": "v1",
              "severity": "high",
              "message": "Resource does not have required tags"
            }
          ],
          "description": "text"
        },
        "backendSummary": {
          "type": "s3",
          "config": {
            "bucket": "terraform-state",
            "key": "prod/terraform.tfstate"
          },
          "resources": 42,
          "description": "text"
        },
        "changedFilesCodeSummary": {
          "total": 5,
          "added": 2,
          "modified": 3,
          "deleted": 0,
          "files": [
            {
              "path": "main.tf",
              "type": "modified"
            }
          ],
          "description": "text"
        },
        "vcsType": {
          "description": "text"
        },
        "runnerType": {
          "description": "text"
        }
      }
    ],
    "apply": [
      {
        "id": "507f1f77bcf86cd799439011",
        "accountId": "507f1f77bcf86cd799439011",
        "createdAt": "2025-08-19T22:12:28.332Z",
        "updatedAt": "2025-08-19T22:12:28.332Z",
        "contentKeys": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "status": "completed",
        "resultStatus": "success",
        "type": {
          "description": "text"
        },
        "guardrailsSummary": {
          "total": 10,
          "passed": 8,
          "failed": 2,
          "violations": [
            {
              "id": "v1",
              "severity": "high",
              "message": "Resource does not have required tags"
            }
          ],
          "description": "text"
        },
        "backendSummary": {
          "type": "s3",
          "config": {
            "bucket": "terraform-state",
            "key": "prod/terraform.tfstate"
          },
          "resources": 42,
          "description": "text"
        },
        "changedFilesCodeSummary": {
          "total": 5,
          "added": 2,
          "modified": 3,
          "deleted": 0,
          "files": [
            {
              "path": "main.tf",
              "type": "modified"
            }
          ],
          "description": "text"
        },
        "vcsType": {
          "description": "text"
        },
        "runnerType": {
          "description": "text"
        }
      }
    ]
  }
]

List Run Resources

post

Lists Resources Affected by a Run

Authorizations
Path parameters
runIdstringRequired

Unique identifier of the Run

Example: 684aac91c3f9b3880d3ece51Pattern: ^[0-9a-fA-F]{24}$
workspaceIdstringRequired

Unique identifier of the Workspace

Example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Query parameters
pageintegerOptionalDefault: 0
pageSizeinteger · min: 1OptionalDefault: 25
Body
all ofOptional
Responses
200

Run resources retrieved successfully

application/json
Responseone of
or
post
POST /v2/workspaces/{workspaceId}/runs/{runId}/resources/search HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 609

{
  "projection": [
    "text"
  ],
  "searchValue": "text",
  "mode": "table",
  "filters": {
    "action": {
      "0": "create"
    },
    "hasDiagnostics": true,
    "taskType": {
      "0": "post-plan"
    },
    "resourceId": {
      "0": "aws_s3_bucket.logs"
    },
    "providerName": [
      "aws"
    ],
    "isDrifted": false,
    "$or": {
      "action": {
        "0": "create"
      },
      "hasDiagnostics": true,
      "taskType": {
        "0": "post-plan"
      },
      "resourceId": {
        "0": "aws_s3_bucket.logs"
      },
      "providerName": [
        "aws"
      ],
      "isDrifted": false
    }
  },
  "sort": {
    "name": {
      "order": -1
    },
    "mode": {
      "order": -1
    },
    "action": {
      "order": -1
    },
    "isDrifted": {
      "order": -1
    },
    "type": {
      "order": -1
    },
    "taskType": {
      "order": -1
    },
    "providerName": {
      "order": -1
    },
    "updatedAt": {
      "order": -1
    },
    "createdAt": {
      "order": -1
    }
  }
}
{
  "resources": [
    {
      "id": "507f1f77bcf86cd799439011",
      "accountId": "507f1f77bcf86cd799439011",
      "createdAt": "2025-08-19T22:12:28.332Z",
      "updatedAt": "2025-08-19T22:12:28.332Z",
      "taskId": "507f1f77bcf86cd799439013",
      "name": "aws_instance.example",
      "type": "aws_instance",
      "mode": "managed",
      "action": {
        "description": "text"
      }
    },
    {
      "isDrifted": false,
      "taskType": {
        "description": "text"
      },
      "dataType": {
        "description": "text"
      },
      "providerName": "aws",
      "providerType": "aws",
      "providerVersion": "4.0.0"
    }
  ]
}

List run changed code

post

Lists code changes grouped by folders with file metadata

Authorizations
Path parameters
runIdstringRequired

Unique identifier of the run

Example: 684aac91c3f9b3880d3ece51Pattern: ^[0-9a-fA-F]{24}$
workspaceIdstringRequired

Unique identifier of the Workspace

Example: 0e01b22c-7f4b-5e0f-b1c1-faff031977f8Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Query parameters
pageintegerOptionalDefault: 0
pageSizeinteger · min: 1OptionalDefault: 25
Body
all ofOptional
Responses
200

Run changed code retrieved successfully

application/json
post
POST /v2/workspaces/{workspaceId}/runs/{runId}/changed-files-code/search HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 410

{
  "projection": [
    "text"
  ],
  "searchValue": "text",
  "filters": {
    "taskId": {
      "0": "507f1f77bcf86cd799439013"
    },
    "suffix": {
      "0": "tf"
    },
    "taskType": {
      "0": "post-plan"
    },
    "filePath": {
      "0": "infrastructure/main.tf"
    },
    "$or": {
      "taskId": {
        "0": "507f1f77bcf86cd799439013"
      },
      "suffix": {
        "0": "tf"
      },
      "taskType": {
        "0": "post-plan"
      },
      "filePath": {
        "0": "infrastructure/main.tf"
      }
    }
  },
  "sort": {
    "taskType": {
      "order": -1
    },
    "suffix": {
      "order": -1
    },
    "updatedAt": {
      "order": -1
    }
  }
}
{
  "infrastructure": [
    {
      "id": "507f1f77bcf86cd799439014",
      "filePath": "infrastructure/main.tf",
      "folderPath": "infrastructure",
      "fileSuffix": "tf",
      "changes": {
        "additions": 10,
        "deletions": 5
      }
    }
  ],
  "modules": [
    {
      "id": "507f1f77bcf86cd799439015",
      "filePath": "modules/network/main.tf",
      "folderPath": "modules/network",
      "fileSuffix": "tf",
      "changes": {
        "additions": 3,
        "deletions": 1
      }
    }
  ]
}

Guardrails

List Guardrail Rules

post

Returns a list of guardrails rules based on filter criteria

Authorizations
Query parameters
pageintegerOptionalDefault: 0
pageSizeinteger · min: 1OptionalDefault: 25
Body
all ofOptional
Responses
200

List of guardrail rules retrieved successfully

application/json
post
POST /v2/guardrails/search HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 496

{
  "projection": [
    "text"
  ],
  "searchValue": "text",
  "filters": {
    "createdBy": [
      "John Doe"
    ],
    "type": [
      "policy",
      "cost"
    ],
    "labels": [
      "production"
    ],
    "repositories": [
      "my-repo"
    ],
    "workspaces": [
      "my-workspace"
    ],
    "branches": [
      "main"
    ],
    "$or": {
      "createdBy": [
        "John Doe"
      ],
      "type": [
        "policy",
        "cost"
      ],
      "labels": [
        "production"
      ],
      "repositories": [
        "my-repo"
      ],
      "workspaces": [
        "my-workspace"
      ],
      "branches": [
        "main"
      ]
    }
  },
  "sort": [
    {
      "createdAt": {
        "order": -1
      },
      "accountId": {
        "order": -1
      },
      "createdBy": {
        "order": -1
      },
      "name": {
        "order": -1
      },
      "severity": {
        "order": -1
      }
    }
  ]
}
[
  {
    "id": "507f1f77bcf86cd799439012",
    "accountId": "507f1f77bcf86cd799439012",
    "createdBy": "John Doe",
    "name": "text",
    "type": "policy",
    "scope": {
      "workspaces": {
        "include": null,
        "exclude": [
          "text"
        ]
      },
      "repositories": {
        "include": null,
        "exclude": [
          "text"
        ]
      },
      "branches": {
        "include": null,
        "exclude": [
          "text"
        ]
      },
      "labels": {
        "include": null,
        "exclude": [
          "text"
        ]
      }
    },
    "criteria": {
      "cost": {
        "thresholdAmount": 1,
        "thresholdPercentage": 1
      },
      "policy": {
        "severity": "text",
        "policies": {
          "include": [
            "text"
          ],
          "exclude": [
            "text"
          ]
        }
      },
      "resource": {
        "actions": [
          "create"
        ],
        "regions": {
          "include": null,
          "exclude": [
            "text"
          ]
        },
        "assetTypes": {
          "include": null,
          "exclude": [
            "text"
          ]
        },
        "specificResources": [
          "text"
        ]
      },
      "tag": {
        "tagEnforcementMode": "anyTags"
      }
    },
    "isEnabled": true,
    "createdAt": "2025-08-19T22:12:28.332Z",
    "updatedAt": "2025-08-19T22:12:28.332Z",
    "notificationId": "507f1f77bcf86cd799439012",
    "severity": 0,
    "enforceOnNoOp": true
  }
]

Create a new Guardrail Rule

post

Creates a new guardrail rule with optional notification setup

Authorizations
Body
all ofOptional
Responses
200

Guardrail Rule Created Successfully

application/json
post
POST /v2/guardrails HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 811

{
  "accountId": "507f1f77bcf86cd799439012",
  "createdBy": "John Doe",
  "name": "text",
  "type": "policy",
  "scope": {
    "workspaces": {
      "include": null,
      "exclude": [
        "text"
      ]
    },
    "repositories": {
      "include": null,
      "exclude": [
        "text"
      ]
    },
    "branches": {
      "include": null,
      "exclude": [
        "text"
      ]
    },
    "labels": {
      "include": null,
      "exclude": [
        "text"
      ]
    }
  },
  "criteria": {
    "cost": {
      "thresholdAmount": 1,
      "thresholdPercentage": 1
    },
    "policy": {
      "severity": "text",
      "policies": {
        "include": [
          "text"
        ],
        "exclude": [
          "text"
        ]
      }
    },
    "resource": {
      "actions": [
        "create"
      ],
      "regions": {
        "include": null,
        "exclude": [
          "text"
        ]
      },
      "assetTypes": {
        "include": null,
        "exclude": [
          "text"
        ]
      },
      "specificResources": [
        "text"
      ]
    },
    "tag": {
      "tagEnforcementMode": "anyTags"
    }
  },
  "isEnabled": true,
  "createdAt": "2025-08-19T22:12:28.332Z",
  "updatedAt": "2025-08-19T22:12:28.332Z",
  "notificationId": "507f1f77bcf86cd799439012",
  "severity": 0,
  "enforceOnNoOp": true
}
{
  "ruleId": "507f1f77bcf86cd799439011",
  "notificationId": "507f1f77bcf86cd799439012"
}

Update a Guardrail Rule

patch

Updates an existing Guardrail Rule and its Notifications

Authorizations
Path parameters
ruleIdstringRequired

Unique identifier of the Guardrail Rule

Example: 684aac91c3f9b3880d3ece51Pattern: ^[0-9a-fA-F]{24}$
Body
all ofOptional
Responses
200

Guardrail Rule Updated Successfully

application/json
patch
PATCH /v2/guardrails/{ruleId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 811

{
  "accountId": "507f1f77bcf86cd799439012",
  "createdBy": "John Doe",
  "name": "text",
  "type": "policy",
  "scope": {
    "workspaces": {
      "include": null,
      "exclude": [
        "text"
      ]
    },
    "repositories": {
      "include": null,
      "exclude": [
        "text"
      ]
    },
    "branches": {
      "include": null,
      "exclude": [
        "text"
      ]
    },
    "labels": {
      "include": null,
      "exclude": [
        "text"
      ]
    }
  },
  "criteria": {
    "cost": {
      "thresholdAmount": 1,
      "thresholdPercentage": 1
    },
    "policy": {
      "severity": "text",
      "policies": {
        "include": [
          "text"
        ],
        "exclude": [
          "text"
        ]
      }
    },
    "resource": {
      "actions": [
        "create"
      ],
      "regions": {
        "include": null,
        "exclude": [
          "text"
        ]
      },
      "assetTypes": {
        "include": null,
        "exclude": [
          "text"
        ]
      },
      "specificResources": [
        "text"
      ]
    },
    "tag": {
      "tagEnforcementMode": "anyTags"
    }
  },
  "isEnabled": true,
  "createdAt": "2025-08-19T22:12:28.332Z",
  "updatedAt": "2025-08-19T22:12:28.332Z",
  "notificationId": "507f1f77bcf86cd799439012",
  "severity": 0,
  "enforceOnNoOp": true
}
{
  "id": "507f1f77bcf86cd799439011",
  "name": "Enforce S3 Encryption",
  "enabled": true,
  "updatedAt": "2024-11-11T10:00:00Z"
}

Delete a Guardrail Rule

delete

Deletes a Guardrail Rule and its Associated Notification

Authorizations
Path parameters
ruleIdstringRequired

Unique identifier of the Guardrail Rule

Example: 684aac91c3f9b3880d3ece51Pattern: ^[0-9a-fA-F]{24}$
Responses
200

Guardrail Rule Deleted Successfully

application/json
delete
DELETE /v2/guardrails/{ruleId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

{
  "status": 200,
  "message": "Guardrail rule and notification deleted successfully"
}

Projects

Create a project

post

Creates a new project

Authorizations
Body
all ofOptional
Responses
201

Project created successfully

application/json
Responseall of
post
POST /v2/runners/projects HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 189

{
  "name": "text",
  "description": "text",
  "labels": [
    "text"
  ],
  "cronExecutionPattern": "text",
  "variables": [
    {
      "key": "text",
      "value": "text",
      "sensitivity": "string",
      "destination": "env"
    }
  ],
  "parentId": "text"
}
{
  "name": "text",
  "description": "text",
  "labels": [
    "text"
  ],
  "cronExecutionPattern": "text",
  "variables": [
    {
      "key": "text",
      "value": "text",
      "sensitivity": "string",
      "destination": "env"
    }
  ],
  "id": "text",
  "accountId": "text",
  "membersCount": 1,
  "workspaceCount": 1,
  "parentId": "text"
}

Get a project

get

Retrieves a single project by ID

Authorizations
Path parameters
projectIdstringRequired

Unique identifier of the project to retrieve

Responses
200

Project retrieved successfully

application/json
Responseall of
get
GET /v2/runners/projects/{projectId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

{
  "name": "text",
  "description": "text",
  "labels": [
    "text"
  ],
  "cronExecutionPattern": "text",
  "variables": [
    {
      "key": "text",
      "value": "text",
      "sensitivity": "string",
      "destination": "env"
    }
  ],
  "id": "text",
  "accountId": "text",
  "membersCount": 1,
  "workspaceCount": 1,
  "parentId": "text"
}

Update a project

patch

Updates an existing project

Authorizations
Path parameters
projectIdstringRequired

Unique identifier of the project to update

Body
all ofOptional
Responses
200

Project updated successfully

application/json
Responseall of
patch
PATCH /v2/runners/projects/{projectId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 171

{
  "name": "text",
  "description": "text",
  "labels": [
    "text"
  ],
  "cronExecutionPattern": "text",
  "variables": [
    {
      "key": "text",
      "value": "text",
      "sensitivity": "string",
      "destination": "env"
    }
  ]
}
{
  "name": "text",
  "description": "text",
  "labels": [
    "text"
  ],
  "cronExecutionPattern": "text",
  "variables": [
    {
      "key": "text",
      "value": "text",
      "sensitivity": "string",
      "destination": "env"
    }
  ],
  "id": "text",
  "accountId": "text",
  "membersCount": 1,
  "workspaceCount": 1,
  "parentId": "text"
}

Delete a project

delete

Deletes a project and all its associated workspaces

Authorizations
Path parameters
projectIdstringRequired

Unique identifier of the project to delete

Responses
204

Project successfully deleted

delete
DELETE /v2/runners/projects/{projectId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

No content

List projects in flat structure

get

Retrieves all projects with pagination support

Authorizations
Query parameters
pageSizeinteger · min: 1OptionalDefault: 25
offsetintegerOptional

The offset of the items to return

Default: 0
maxDepthinteger · max: 5Optional

Maximum depth of the project tree to return

Responses
200

Projects retrieved successfully in flat list format

application/json
get
GET /v2/runners/projects/list HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

{
  "data": [
    {
      "name": "text",
      "description": "text",
      "labels": [
        "text"
      ],
      "cronExecutionPattern": "text",
      "variables": [
        {
          "key": "text",
          "value": "text",
          "sensitivity": "string",
          "destination": "env"
        }
      ],
      "id": "text",
      "accountId": "text",
      "membersCount": 1,
      "workspaceCount": 1,
      "parentId": "text"
    }
  ],
  "totalCount": 1
}

List projects in tree structure

get

Retrieves all projects in a hierarchical tree format

Authorizations
Query parameters
searchQuerystringOptional

Search query

variableSetIdstringOptional

Filter projects by variable set ID

consumedOnlybooleanOptional

When used with variableSetId, only return projects that consume the variable set

Responses
200

Projects retrieved successfully in tree format

application/json
get
GET /v2/runners/projects/tree HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

{
  "data": [
    {
      "data": [
        {
          "name": "text",
          "description": "text",
          "labels": [
            "text"
          ],
          "cronExecutionPattern": "text",
          "variables": [
            {
              "key": "text",
              "value": "text",
              "sensitivity": "string",
              "destination": "env"
            }
          ],
          "id": "text",
          "accountId": "text",
          "membersCount": 1,
          "workspaceCount": 1,
          "parentId": "text"
        },
        {
          "hasChildren": true,
          "children": [
            {
              "name": "text",
              "description": "text",
              "labels": [
                "text"
              ],
              "cronExecutionPattern": "text",
              "variables": [
                {
                  "key": "text",
                  "value": "text",
                  "sensitivity": "string",
                  "destination": "env"
                }
              ],
              "id": "text",
              "accountId": "text",
              "membersCount": 1,
              "workspaceCount": 1,
              "parentId": "text"
            }
          ],
          "ancestors": [
            {
              "name": "text",
              "description": "text",
              "labels": [
                "text"
              ],
              "cronExecutionPattern": "text",
              "variables": [
                {
                  "key": "text",
                  "value": "text",
                  "sensitivity": "string",
                  "destination": "env"
                }
              ],
              "id": "text",
              "accountId": "text",
              "membersCount": 1,
              "workspaceCount": 1,
              "parentId": "text"
            }
          ]
        }
      ]
    }
  ]
}

List members of a project

get

Retrieves all members of a specified project

Authorizations
Path parameters
projectIdstringRequired

Unique identifier of the project

Responses
200

Members retrieved successfully

application/json
get
GET /v2/runners/projects/{projectId}/members HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

[
  {
    "userId": "text",
    "role": "admin"
  }
]

Add members to a project

post

Adds new members to a specified project

Authorizations
Path parameters
projectIdstringRequired

Unique identifier of the project

Bodyobject[]
userIdstringRequired

ID of the user

rolestring · enumRequired

Role of the user in the project

Possible values:
Responses
201

Members added successfully

application/json
post
POST /v2/runners/projects/{projectId}/members HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 34

[
  {
    "userId": "text",
    "role": "admin"
  }
]
[
  {
    "userId": "text",
    "role": "admin"
  }
]

Remove members from a project

delete

Deletes specified members from a project

Authorizations
Path parameters
projectIdstringRequired

Unique identifier of the project

Bodystring[]
string[]Optional

User IDs of the members to remove

Responses
204

Members removed successfully

delete
DELETE /v2/runners/projects/{projectId}/members HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 8

[
  "text"
]
No content

List workspaces of a project

get

Retrieves all workspaces of a specified project

Authorizations
Path parameters
projectIdstringRequired

Unique identifier of the project

Query parameters
searchQuerystringOptional

Search query

pageSizeinteger · min: 1OptionalDefault: 25
offsetintegerOptional

The offset of the items to return

Default: 0
Responses
200

Workspaces retrieved successfully

application/json
get
GET /v2/runners/projects/{projectId}/workspaces HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

[
  {
    "id": "text",
    "name": "text",
    "description": "text",
    "accountId": "text",
    "repository": "text",
    "workingDirectory": "text",
    "vcsIntegrationId": "text",
    "vcs": "text",
    "defaultBranch": "text",
    "cronExecutionPattern": "text",
    "iacProvisioner": {
      "type": "terraform",
      "version": "text"
    },
    "labels": [
      "text"
    ]
  }
]

List all project labels

get

Retrieves all available project labels for the account

Authorizations
Responses
200

Project labels retrieved successfully

application/json
Responsestring[]

List of project labels

get
GET /v2/runners/projects/labels HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

[
  "text"
]

Variables Management

Project Variables

List variables for a project

get
Authorizations
Path parameters
projectIdstringRequired
Responses
200

List of project variables

application/json
get
GET /v2/runners/variables/projects/{projectId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*
200

List of project variables

[
  {
    "key": "text",
    "value": "text",
    "description": "text",
    "isSecret": true,
    "projectId": "text",
    "workspaceId": "text",
    "variableSetId": "text",
    "createdAt": "2025-08-19T22:12:28.332Z",
    "updatedAt": "2025-08-19T22:12:28.332Z",
    "sensitivity": "string",
    "destination": "env",
    "origin": "project"
  }
]

Upsert variables within a project (create or update)

post
Authorizations
Path parameters
projectIdstringRequired
Body
Responses
200

Variables upserted within project

application/json
post
POST /v2/runners/variables/projects/{projectId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 88

{
  "variables": [
    {
      "key": "text",
      "value": "text",
      "sensitivity": "string",
      "destination": "env"
    }
  ]
}
200

Variables upserted within project

[
  {
    "key": "text",
    "value": "text",
    "description": "text",
    "isSecret": true,
    "projectId": "text",
    "workspaceId": "text",
    "variableSetId": "text",
    "createdAt": "2025-08-19T22:12:28.332Z",
    "updatedAt": "2025-08-19T22:12:28.332Z",
    "sensitivity": "string",
    "destination": "env",
    "origin": "project"
  }
]

Delete variables from a project

delete
Authorizations
Path parameters
projectIdstringRequired
Body
variableKeysstring[] · min: 1Required

Array of variable keys to delete

Responses
204

Variables deleted from project

delete
DELETE /v2/runners/variables/projects/{projectId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "variableKeys": [
    "text"
  ]
}
204

Variables deleted from project

No content

Workspace Variables

List variables for a workspace

get
Authorizations
Path parameters
workspaceIdstringRequired
Query parameters
pageSizeintegerOptional
offsetintegerOptional
Responses
200

List of workspace variables

application/json
get
GET /v2/runners/variables/workspaces/{workspaceId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*
200

List of workspace variables

[
  {
    "key": "text",
    "value": "text",
    "sensitivity": "string",
    "destination": "env"
  }
]

Upsert variables within a workspace (create or update)

post
Authorizations
Path parameters
workspaceIdstringRequired
Body
Responses
200

Variables upserted within workspace

application/json
post
POST /v2/runners/variables/workspaces/{workspaceId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 144

{
  "variables": [
    {
      "variableId": "text",
      "variableData": {
        "key": "text",
        "value": "text",
        "sensitivity": "string",
        "destination": "env",
        "origin": "project"
      }
    }
  ]
}
200

Variables upserted within workspace

[
  {
    "key": "text",
    "value": "text",
    "sensitivity": "string",
    "destination": "env"
  }
]

Delete variables from a workspace

delete
Authorizations
Path parameters
workspaceIdstringRequired
Body
variableIdsstring[] · min: 1Required

Array of variable IDs to delete

Responses
204

Variables deleted from workspace

delete
DELETE /v2/runners/variables/workspaces/{workspaceId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 24

{
  "variableIds": [
    "text"
  ]
}
204

Variables deleted from workspace

No content

Variable Sets

List variable sets

get
Authorizations
Query parameters
searchQuerystringOptional
pageSizeintegerOptional
offsetintegerOptional
Responses
200

List of variable sets

application/json
get
GET /v2/runners/variables/variable-sets HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*
200

List of variable sets

[
  {
    "key": "text",
    "value": "text",
    "sensitivity": "string",
    "destination": "env"
  }
]

Create a new variable set

post
Authorizations
Body
namestringRequired

Name of the variable set

descriptionstringOptional

Description of the variable set

labelsstring[]Optional

Labels to assign to the variable set

parentsstring[]Optional

Parent variable set IDs

Responses
201

Variable set created successfully

application/json
post
POST /v2/runners/variables/variable-sets HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "name": "text",
  "description": "text",
  "labels": [
    "text"
  ],
  "parents": [
    "text"
  ],
  "variables": [
    {
      "key": "text",
      "value": "text",
      "sensitivity": "string",
      "destination": "env"
    }
  ]
}
{
  "variableSetId": "text"
}

Get a variable set

get
Authorizations
Path parameters
variableSetIdstringRequired
Responses
200

Variable set

application/json
get
GET /v2/runners/variables/variable-sets/{variableSetId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

{
  "id": "text",
  "version": 1,
  "name": "text",
  "description": "text",
  "labels": [
    "text"
  ],
  "parents": [
    "text"
  ],
  "variables": [
    {
      "key": "text",
      "value": "text",
      "sensitivity": "string",
      "destination": "env"
    }
  ],
  "descendants": [
    {
      "id": "text",
      "name": "text"
    }
  ],
  "consumers": {
    "workspaces": [
      {
        "id": "text",
        "name": "text"
      }
    ],
    "projects": [
      {
        "id": "text",
        "name": "text"
      }
    ]
  }
}

Update a variable set

put
Authorizations
Path parameters
variableSetIdstringRequired
Body
namestringOptional

Name of the variable set

descriptionstringOptional

Description of the variable set

labelsstring[]Optional

Labels to assign to the variable set

parentsstring[]Optional

Parent variable set IDs

Responses
200

Variable set updated successfully

application/json
put
PUT /v2/runners/variables/variable-sets/{variableSetId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "name": "text",
  "description": "text",
  "labels": [
    "text"
  ],
  "parents": [
    "text"
  ],
  "variables": [
    {
      "key": "text",
      "value": "text",
      "sensitivity": "string",
      "destination": "env"
    }
  ]
}
{
  "id": "text",
  "version": 1,
  "name": "text",
  "description": "text",
  "labels": [
    "text"
  ],
  "parents": [
    "text"
  ],
  "variables": [
    {
      "key": "text",
      "value": "text",
      "sensitivity": "string",
      "destination": "env"
    }
  ],
  "descendants": [
    {
      "id": "text",
      "name": "text"
    }
  ],
  "consumers": {
    "workspaces": [
      {
        "id": "text",
        "name": "text"
      }
    ],
    "projects": [
      {
        "id": "text",
        "name": "text"
      }
    ]
  }
}

Delete a variable set

delete
Authorizations
Path parameters
variableSetIdstringRequired
Responses
204

Variable set deleted successfully

delete
DELETE /v2/runners/variables/variable-sets/{variableSetId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

No content

List variables in a variable set

get
Authorizations
Path parameters
variableSetIdstringRequired
Query parameters
pageintegerOptionalDefault: 0
pageSizeinteger · min: 1OptionalDefault: 25
Responses
200

List of variables in variable set

application/json
get
GET /v2/runners/variables/variable-sets/{variableSetId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*
200

List of variables in variable set

[
  {
    "key": "text",
    "value": "text",
    "sensitivity": "string",
    "destination": "env"
  }
]

Upsert variables within a variable set (create or update)

post
Authorizations
Path parameters
variableSetIdstringRequired
Body
Responses
200

Variables upserted within variable set

application/json
post
POST /v2/runners/variables/variable-sets/{variableSetId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 88

{
  "variables": [
    {
      "key": "text",
      "value": "text",
      "sensitivity": "string",
      "destination": "env"
    }
  ]
}
200

Variables upserted within variable set

[
  {
    "key": "text",
    "value": "text",
    "sensitivity": "string",
    "destination": "env"
  }
]

Delete variables from a variable set

delete
Authorizations
Path parameters
variableSetIdstringRequired
Body
variableIdsstring[] · min: 1Required

Array of variable IDs to delete

Responses
204

Variables deleted from variable set

delete
DELETE /v2/runners/variables/variable-sets/{variableSetId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 24

{
  "variableIds": [
    "text"
  ]
}
204

Variables deleted from variable set

No content

Variable Set Operations

Attach a variable set to a project

post
Authorizations
Path parameters
projectIdstringRequired
variableSetIdstringRequired
Body
consumebooleanRequired

Whether to consume the variable set values

Default: true
Responses
204

Variable set attached to project

post
POST /v2/runners/variables/projects/{projectId}/variable-sets/{variableSetId}/attach HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "consume": true
}
204

Variable set attached to project

No content

Detach a variable set from a project

post
Authorizations
Path parameters
projectIdstringRequired
variableSetIdstringRequired
Responses
204

Variable set detached from project

post
POST /v2/runners/variables/projects/{projectId}/variable-sets/{variableSetId}/detach HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*
204

Variable set detached from project

No content

Bind a variable set to a workspace

post
Authorizations
Path parameters
workspaceIdstringRequired
variableSetIdstringRequired
Responses
204

Variable set bound to workspace

post
POST /v2/runners/variables/workspaces/{workspaceId}/variable-sets/{variableSetId}/bind HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*
204

Variable set bound to workspace

No content

Unbind a variable set from a workspace

post
Authorizations
Path parameters
workspaceIdstringRequired
variableSetIdstringRequired
Responses
204

Variable set unbound from workspace

post
POST /v2/runners/variables/workspaces/{workspaceId}/variable-sets/{variableSetId}/unbind HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*
204

Variable set unbound from workspace

No content

Runners Workspaces

Create a new workspace

post

Creates a new workspace with the provided configuration

Authorizations
Body
runnerTypestringRequired

Type of runner (e.g., firefly_runners)

Example: firefly_runners
iacTypestringRequired

Infrastructure as Code type

Example: terraform
workspaceNamestringRequired

Unique workspace name

Example: my-workspace
descriptionstringOptional

Workspace description

Example: Production environment workspace
labelsstring[]Optional

Labels assigned to the workspace

Example: ["production","terraform"]
vcsIdstringRequired

VCS integration ID

Example: 5fd126f5744410407fbc552f
repostringRequired

Repository name

Example: infralight/appiac
defaultBranchstringRequired

Default branch

Example: main
vcsTypestringRequired

VCS type (github, gitlab, etc.)

Example: github
workDirstringRequired

Working directory path

Example: terraform/production
projectstring | nullableOptional

Project ID or null for global access

terraformVariablesobjectOptional

Cleaned by deleteMockArrays

terraformSensitiveVariablesobjectOptional

Cleaned by deleteMockArrays

providersCredentialsobjectOptional

Cleaned by deleteMockArrays

runnerEnvironmentobjectOptional

Cleaned by deleteMockArrays

Responses
201

Workspace created successfully

application/json
post
POST /v2/runners/workspaces HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 598

{
  "runnerType": "firefly_runners",
  "iacType": "terraform",
  "workspaceName": "my-workspace",
  "description": "Production environment workspace",
  "labels": [
    "production",
    "terraform"
  ],
  "vcsId": "5fd126f5744410407fbc552f",
  "repo": "infralight/appiac",
  "defaultBranch": "main",
  "vcsType": "github",
  "workDir": "terraform/production",
  "variables": [
    {
      "key": "text",
      "value": "text",
      "sensitivity": "string",
      "destination": "env"
    }
  ],
  "execution": {
    "triggers": [
      "merge"
    ],
    "applyRule": "manual",
    "terraformVersion": "1.5.7"
  },
  "project": null,
  "terraformVariables": {},
  "terraformSensitiveVariables": {},
  "providersCredentials": {},
  "runnerEnvironment": {}
}
{
  "id": "text",
  "name": "text",
  "description": "text",
  "accountId": "text",
  "repository": "text",
  "workingDirectory": "text",
  "vcsIntegrationId": "text",
  "vcs": "text",
  "defaultBranch": "text",
  "cronExecutionPattern": "text",
  "iacProvisioner": {
    "type": "terraform",
    "version": "text"
  },
  "labels": [
    "text"
  ]
}

List all workspace labels

get

Retrieves all available workspace labels for the account

Authorizations
Responses
200

Workspace labels retrieved successfully

application/json
Responsestring[]

List of workspace labels

get
GET /v2/runners/workspaces/labels HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

[
  "text"
]

Get workspace details

get

Retrieves details for a specific workspace

Authorizations
Path parameters
workspaceIdstringRequired

Unique identifier of the workspace

Responses
200

Workspace details retrieved successfully

application/json
get
GET /v2/runners/workspaces/{workspaceId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

{
  "id": "text",
  "name": "text",
  "description": "text",
  "accountId": "text",
  "repository": "text",
  "workingDirectory": "text",
  "vcsIntegrationId": "text",
  "vcs": "text",
  "defaultBranch": "text",
  "cronExecutionPattern": "text",
  "iacProvisioner": {
    "type": "terraform",
    "version": "text"
  },
  "labels": [
    "text"
  ]
}

Deploy workspace

post

Deploys a workspace by running plan or apply tasks based on the provided task type

Authorizations
Path parameters
workspaceIdstringRequired

Unique identifier of the workspace

Body
taskTypestring · enumRequired

The type of task to run (plan or apply)

Possible values:
cmdArgumentsstringOptional

Additional command line arguments

Responses
200

Workspace deployed successfully

application/json
post
POST /v2/runners/workspaces/{workspaceId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 112

{
  "taskType": "plan",
  "vcs": {
    "reference": "text",
    "type": "branch"
  },
  "trigger": {
    "type": "manual"
  },
  "cmdArguments": "text"
}
{
  "status": 200,
  "data": {
    "message": "Workspace deployed successfully"
  }
}

Update a workspace

put

Updates an existing workspace with the provided configuration

Authorizations
Path parameters
workspaceIdstringRequired

Unique identifier of the workspace

Body
namestringOptional

Workspace name

Example: my-workspace
descriptionstringOptional

Workspace description

Example: Production environment workspace
labelsstring[]Optional

Labels assigned to the workspace

Example: ["production","terraform"]
vcsIntegrationIdstringOptional

VCS integration ID

Example: 5fd126f5744410407fbc552f
repositorystringOptional

Repository name

Example: infralight/appiac
defaultBranchstringOptional

Default branch

Example: main
vcsstringOptional

VCS type (github, gitlab, etc.)

Example: github
workingDirectorystringOptional

Working directory path

Example: terraform/production
runnerTypestringOptional

Type of runner (e.g., firefly_runners)

Example: firefly_runners
cronExecutionPatternstringOptional

Cron pattern for scheduled executions

Example: 0 2 * * *
parentIdstring | nullableOptional

Project ID or null for global access

Responses
200

Workspace updated successfully

application/json
put
PUT /v2/runners/workspaces/{workspaceId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 482

{
  "name": "my-workspace",
  "description": "Production environment workspace",
  "labels": [
    "production",
    "terraform"
  ],
  "vcsIntegrationId": "5fd126f5744410407fbc552f",
  "repository": "infralight/appiac",
  "defaultBranch": "main",
  "vcs": "github",
  "workingDirectory": "terraform/production",
  "iacProvisioner": {
    "type": "terraform",
    "version": "text"
  },
  "runnerType": "firefly_runners",
  "triggerConfig": {
    "runOnPullRequest": true,
    "runOnPush": false,
    "autoApply": false
  },
  "cronExecutionPattern": "0 2 * * *",
  "parentId": null
}
{
  "id": "text",
  "name": "text",
  "description": "text",
  "accountId": "text",
  "repository": "text",
  "workingDirectory": "text",
  "vcsIntegrationId": "text",
  "vcs": "text",
  "defaultBranch": "text",
  "cronExecutionPattern": "text",
  "iacProvisioner": {
    "type": "terraform",
    "version": "text"
  },
  "labels": [
    "text"
  ]
}

Delete a workspace

delete

Deletes a specific workspace and optionally destroys its infrastructure resources

Authorizations
Path parameters
workspaceIdstringRequired

Unique identifier of the workspace

Query parameters
destroybooleanOptional

Whether to destroy infrastructure resources before deleting the workspace

Default: false
descriptionstringOptional

Optional description for the deletion operation

Responses
200

Workspace deleted successfully

application/json
delete
DELETE /v2/runners/workspaces/{workspaceId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Accept: */*

{
  "message": "Workspace deleted successfully",
  "workspaceId": "text",
  "resourcesDestroyed": true
}

Destroy workspace infrastructure resources

post

Initiates a destroy task to clean up cloud infrastructure resources managed by this workspace. This does not delete the workspace entity itself.

Authorizations
Path parameters
workspaceIdstringRequired

Unique identifier of the workspace

Body

Request to run a task on workspace infrastructure

descriptionstringOptional

Optional description for the task

Example: Running infrastructure task
cmdArgumentsstringOptional

Optional command line arguments for the task

Example: -auto-approve
Responses
200

Destroy task initiated successfully

application/json
post
POST /v2/runners/workspaces/{workspaceId}/tasks/destroy HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 166

{
  "description": "Running infrastructure task",
  "vcs": {
    "reference": "main",
    "type": "branch"
  },
  "trigger": {
    "type": "manual",
    "source": "Firefly"
  },
  "cmdArguments": "-auto-approve"
}
{
  "accountId": "text",
  "id": "text",
  "status": "pending",
  "error": {
    "type": "UNEXPECTED",
    "description": "text"
  },
  "currentStep": "plan",
  "workspaceId": "text",
  "vcs": {
    "reference": "main",
    "type": "branch"
  },
  "trigger": {
    "type": "manual"
  },
  "type": "plan",
  "cmdArguments": "text",
  "createdAt": "2025-08-19T22:12:28.332Z",
  "updatedAt": "2025-08-19T22:12:28.332Z"
}
PreviousCodificationNextSelf-Service

Last updated

Was this helpful?