Workflows

Workspaces

List Workspaces

post

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

Authorizations
AuthorizationstringRequired

JWT authentication token

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

List of Workspaces Retrieved Successfully

application/json
post
/workspaces/search
POST /v2/workspaces/search HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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-11-16T03:17:54.832Z",
    "updatedAt": "2025-11-16T03:17:54.832Z",
    "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-11-16T03:17:54.832Z",
    "lastPlanTime": "2025-11-16T03:17:54.832Z",
    "lastRunTime": "2025-11-16T03:17:54.832Z",
    "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
AuthorizationstringRequired

JWT authentication token

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
/workspaces/{workspaceId}
DELETE /v2/workspaces/{workspaceId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Update Workspace Labels

put

Updates Labels for a specific Workspace

Authorizations
AuthorizationstringRequired

JWT authentication token

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
/workspaces/{workspaceId}/labels
PUT /v2/workspaces/{workspaceId}/labels HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "labels": [
    "text"
  ]
}
{
  "id": "507f1f77bcf86cd799439015",
  "workspaceName": "production-infra",
  "labels": [
    "production",
    "terraform",
    "critical"
  ],
  "updatedAt": "2025-11-16T03:17:54.832Z"
}

List Workspace Runs

post

Lists all Runs for a specific Workspace

Authorizations
AuthorizationstringRequired

JWT authentication token

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
/workspaces/{workspaceId}/runs/search
POST /v2/workspaces/{workspaceId}/runs/search HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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-11-16T03:17:54.832Z",
    "updatedAt": "2025-11-16T03:17:54.832Z",
    "$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-11-16T03:17:54.832Z",
      "updatedAt": "2025-11-16T03:17:54.832Z"
    }
  },
  "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-11-16T03:17:54.832Z",
    "updatedAt": "2025-11-16T03:17:54.832Z",
    "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-11-16T03:17:54.832Z",
        "updatedAt": "2025-11-16T03:17:54.832Z",
        "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-11-16T03:17:54.832Z",
        "updatedAt": "2025-11-16T03:17:54.832Z",
        "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
AuthorizationstringRequired

JWT authentication token

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
/workspaces/{workspaceId}/runs/{runId}/resources/search
POST /v2/workspaces/{workspaceId}/runs/{runId}/resources/search HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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-11-16T03:17:54.832Z",
      "updatedAt": "2025-11-16T03:17:54.832Z",
      "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
AuthorizationstringRequired

JWT authentication token

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
/workspaces/{workspaceId}/runs/{runId}/changed-files-code/search
POST /v2/workspaces/{workspaceId}/runs/{runId}/changed-files-code/search HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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

List of guardrail rules retrieved successfully

application/json
post
/guardrails/search
POST /v2/guardrails/search HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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-11-16T03:17:54.832Z",
    "updatedAt": "2025-11-16T03:17:54.832Z",
    "notificationId": "507f1f77bcf86cd799439012",
    "severity": 0,
    "enforceOnNoOp": true
  }
]

Create a new Guardrail Rule

post

Creates a new guardrail rule with optional notification setup

Authorizations
AuthorizationstringRequired

JWT authentication token

Body
all ofOptional
Responses
200

Guardrail Rule Created Successfully

application/json
post
/guardrails
POST /v2/guardrails HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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-11-16T03:17:54.832Z",
  "updatedAt": "2025-11-16T03:17:54.832Z",
  "notificationId": "507f1f77bcf86cd799439012",
  "severity": 0,
  "enforceOnNoOp": true
}
{
  "ruleId": "507f1f77bcf86cd799439011",
  "notificationId": "507f1f77bcf86cd799439012"
}

Update a Guardrail Rule

patch

Updates an existing Guardrail Rule and its Notifications

Authorizations
AuthorizationstringRequired

JWT authentication token

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
/guardrails/{ruleId}
PATCH /v2/guardrails/{ruleId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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-11-16T03:17:54.832Z",
  "updatedAt": "2025-11-16T03:17:54.832Z",
  "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
AuthorizationstringRequired

JWT authentication token

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
/guardrails/{ruleId}
DELETE /v2/guardrails/{ruleId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Projects

Create a project

post

Creates a new project

Authorizations
AuthorizationstringRequired

JWT authentication token

Body
all ofOptional
Responses
post
/runners/projects
POST /v2/runners/projects HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

Path parameters
projectIdstringRequired

Unique identifier of the project to retrieve

Responses
200

Project retrieved successfully

application/json
Responseall of
get
/runners/projects/{projectId}
GET /v2/runners/projects/{projectId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

Path parameters
projectIdstringRequired

Unique identifier of the project to update

Body
all ofOptional
Responses
200

Project updated successfully

application/json
Responseall of
patch
/runners/projects/{projectId}
PATCH /v2/runners/projects/{projectId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

Path parameters
projectIdstringRequired

Unique identifier of the project to delete

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

No content

List projects in flat structure

get

Retrieves all projects with pagination support

Authorizations
AuthorizationstringRequired

JWT authentication token

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
/runners/projects/list
GET /v2/runners/projects/list HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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
/runners/projects/tree
GET /v2/runners/projects/tree HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

Path parameters
projectIdstringRequired

Unique identifier of the project

Responses
200

Members retrieved successfully

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

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

Add members to a project

post

Adds new members to a specified project

Authorizations
AuthorizationstringRequired

JWT authentication token

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
post
/runners/projects/{projectId}/members
POST /v2/runners/projects/{projectId}/members HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

Path parameters
projectIdstringRequired

Unique identifier of the project

Bodystring[]
string[]Optional

User IDs of the members to remove

Responses
delete
/runners/projects/{projectId}/members
DELETE /v2/runners/projects/{projectId}/members HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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
/runners/projects/{projectId}/workspaces
GET /v2/runners/projects/{projectId}/workspaces HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

Responses
200

Project labels retrieved successfully

application/json
Responsestring[]

List of project labels

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

[
  "text"
]

Variables Management

Project Variables

List variables for a project

get
Authorizations
AuthorizationstringRequired

JWT authentication token

Path parameters
projectIdstringRequired
Responses
200

List of project variables

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

List of project variables

[
  {
    "key": "text",
    "value": "text",
    "description": "text",
    "isSecret": true,
    "projectId": "text",
    "workspaceId": "text",
    "variableSetId": "text",
    "createdAt": "2025-11-16T03:17:54.832Z",
    "updatedAt": "2025-11-16T03:17:54.832Z",
    "sensitivity": "string",
    "destination": "env",
    "origin": "project"
  }
]

Upsert variables within a project (create or update)

post
Authorizations
AuthorizationstringRequired

JWT authentication token

Path parameters
projectIdstringRequired
Body
Responses
200

Variables upserted within project

application/json
post
/runners/variables/projects/{projectId}/variables
POST /v2/runners/variables/projects/{projectId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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-11-16T03:17:54.832Z",
    "updatedAt": "2025-11-16T03:17:54.832Z",
    "sensitivity": "string",
    "destination": "env",
    "origin": "project"
  }
]

Delete variables from a project

delete
Authorizations
AuthorizationstringRequired

JWT authentication token

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

Array of variable keys to delete

Responses
delete
/runners/variables/projects/{projectId}/variables
DELETE /v2/runners/variables/projects/{projectId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

Path parameters
workspaceIdstringRequired
Query parameters
pageSizeintegerOptional
offsetintegerOptional
Responses
200

List of workspace variables

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

List of workspace variables

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

Upsert variables within a workspace (create or update)

post
Authorizations
AuthorizationstringRequired

JWT authentication token

Path parameters
workspaceIdstringRequired
Body
Responses
200

Variables upserted within workspace

application/json
post
/runners/variables/workspaces/{workspaceId}/variables
POST /v2/runners/variables/workspaces/{workspaceId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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

Array of variable IDs to delete

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

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

Variables deleted from workspace

No content

Variable Sets

List variable sets

get
Authorizations
AuthorizationstringRequired

JWT authentication token

Query parameters
searchQuerystringOptional
pageSizeintegerOptional
offsetintegerOptional
Responses
200

List of variable sets

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

List of variable sets

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

Create a new variable set

post
Authorizations
AuthorizationstringRequired

JWT authentication token

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
post
/runners/variables/variable-sets
POST /v2/runners/variables/variable-sets HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

Path parameters
variableSetIdstringRequired
Responses
200

Variable set

application/json
get
/runners/variables/variable-sets/{variableSetId}
GET /v2/runners/variables/variable-sets/{variableSetId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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
/runners/variables/variable-sets/{variableSetId}
PUT /v2/runners/variables/variable-sets/{variableSetId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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

No content

List variables in a variable set

get
Authorizations
AuthorizationstringRequired

JWT authentication token

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

List of variables in variable set

application/json
get
/runners/variables/variable-sets/{variableSetId}/variables
GET /v2/runners/variables/variable-sets/{variableSetId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

Path parameters
variableSetIdstringRequired
Body
Responses
200

Variables upserted within variable set

application/json
post
/runners/variables/variable-sets/{variableSetId}/variables
POST /v2/runners/variables/variable-sets/{variableSetId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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

Array of variable IDs to delete

Responses
delete
/runners/variables/variable-sets/{variableSetId}/variables
DELETE /v2/runners/variables/variable-sets/{variableSetId}/variables HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

Path parameters
projectIdstringRequired
variableSetIdstringRequired
Body
consumebooleanRequired

Whether to consume the variable set values

Default: true
Responses
post
/runners/variables/projects/{projectId}/variable-sets/{variableSetId}/attach
POST /v2/runners/variables/projects/{projectId}/variable-sets/{variableSetId}/attach HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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

Variable set detached from project

No content

Bind a variable set to a workspace

post
Authorizations
AuthorizationstringRequired

JWT authentication token

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

Variable set bound to workspace

No content

Unbind a variable set from a workspace

post
Authorizations
AuthorizationstringRequired

JWT authentication token

Path parameters
workspaceIdstringRequired
variableSetIdstringRequired
Responses
post
/runners/variables/workspaces/{workspaceId}/variable-sets/{variableSetId}/unbind
POST /v2/runners/variables/workspaces/{workspaceId}/variable-sets/{variableSetId}/unbind HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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
consumedVariableSetsstring[]Optional

Array of variable set IDs that this workspace consumes

Example: ["var-set-1","var-set-2"]
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
post
/runners/workspaces
POST /v2/runners/workspaces HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 647

{
  "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"
    }
  ],
  "consumedVariableSets": [
    "var-set-1",
    "var-set-2"
  ],
  "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
AuthorizationstringRequired

JWT authentication token

Responses
200

Workspace labels retrieved successfully

application/json
Responsestring[]

List of workspace labels

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

[
  "text"
]

Get workspace details

get

Retrieves details for a specific workspace

Authorizations
AuthorizationstringRequired

JWT authentication token

Path parameters
workspaceIdstringRequired

Unique identifier of the workspace

Responses
200

Workspace details retrieved successfully

application/json
get
/runners/workspaces/{workspaceId}
GET /v2/runners/workspaces/{workspaceId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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
/runners/workspaces/{workspaceId}
POST /v2/runners/workspaces/{workspaceId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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
/runners/workspaces/{workspaceId}
PUT /v2/runners/workspaces/{workspaceId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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
/runners/workspaces/{workspaceId}
DELETE /v2/runners/workspaces/{workspaceId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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
AuthorizationstringRequired

JWT authentication token

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
/runners/workspaces/{workspaceId}/tasks/destroy
POST /v2/runners/workspaces/{workspaceId}/tasks/destroy HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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-11-16T03:17:54.832Z",
  "updatedAt": "2025-11-16T03:17:54.832Z"
}
PreviousCodificationNextSelf-Service

Last updated

Was this helpful?