Workflows

Workspaces

List Workspaces

post

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

Authorizations

JWTAuth

AuthorizationstringRequired

JWT authentication token

Query parameters

pageintegerOptionalDefault: 0

pageSizeinteger · min: 1OptionalDefault: 25

Body

application/json

Responses

200

List of Workspaces Retrieved Successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

post

/workspaces/search

HTTPcURLJavaScriptPython

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-12-30T22:48:35.249Z",
    "updatedAt": "2025-12-30T22:48:35.249Z",
    "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-12-30T22:48:35.249Z",
    "lastPlanTime": "2025-12-30T22:48:35.249Z",
    "lastRunTime": "2025-12-30T22:48:35.249Z",
    "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

JWTAuth

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

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

delete

/workspaces/{workspaceId}

HTTPcURLJavaScriptPython

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

JWTAuth

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

application/json

labelsstring[]Required

List of labels to assign to the workspace

Responses

200

Workspace Labels Updated Successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

put

/workspaces/{workspaceId}/labels

HTTPcURLJavaScriptPython

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-12-30T22:48:35.249Z"
}

List Workspace Runs

post

Lists all Runs for a specific Workspace

Authorizations

JWTAuth

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

application/json

Responses

200

List of Workspace Runs Retrieved Successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

post

/workspaces/{workspaceId}/runs/search

HTTPcURLJavaScriptPython

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-12-30T22:48:35.249Z",
    "updatedAt": "2025-12-30T22:48:35.249Z",
    "$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-12-30T22:48:35.249Z",
      "updatedAt": "2025-12-30T22:48:35.249Z"
    }
  },
  "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-12-30T22:48:35.249Z",
    "updatedAt": "2025-12-30T22:48:35.249Z",
    "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-12-30T22:48:35.249Z",
        "updatedAt": "2025-12-30T22:48:35.249Z",
        "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-12-30T22:48:35.249Z",
        "updatedAt": "2025-12-30T22:48:35.249Z",
        "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

JWTAuth

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

application/json

Responses

200

Run resources retrieved successfully

application/json

Responseone of

or

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

post

/workspaces/{workspaceId}/runs/{runId}/resources/search

HTTPcURLJavaScriptPython

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-12-30T22:48:35.249Z",
      "updatedAt": "2025-12-30T22:48:35.249Z",
      "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

JWTAuth

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

application/json

Responses

200

Run changed code retrieved successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

post

/workspaces/{workspaceId}/runs/{runId}/changed-files-code/search

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Query parameters

pageintegerOptionalDefault: 0

pageSizeinteger · min: 1OptionalDefault: 25

Body

application/json

Responses

200

List of guardrail rules retrieved successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

post

/guardrails/search

HTTPcURLJavaScriptPython

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-12-30T22:48:35.249Z",
    "updatedAt": "2025-12-30T22:48:35.249Z",
    "notificationId": "507f1f77bcf86cd799439012",
    "severity": 0,
    "enforceOnNoOp": true
  }
]

Create a new Guardrail Rule

post

Creates a new guardrail rule with optional notification setup

Authorizations

JWTAuth

AuthorizationstringRequired

JWT authentication token

Body

application/json

Responses

200

Guardrail Rule Created Successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

post

/guardrails

HTTPcURLJavaScriptPython

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-12-30T22:48:35.249Z",
  "updatedAt": "2025-12-30T22:48:35.249Z",
  "notificationId": "507f1f77bcf86cd799439012",
  "severity": 0,
  "enforceOnNoOp": true
}

{
  "ruleId": "507f1f77bcf86cd799439011",
  "notificationId": "507f1f77bcf86cd799439012"
}

Update a Guardrail Rule

patch

Updates an existing Guardrail Rule and its Notifications

Authorizations

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

ruleIdstringRequired

Unique identifier of the Guardrail Rule

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

Body

application/json

Responses

200

Guardrail Rule Updated Successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

patch

/guardrails/{ruleId}

HTTPcURLJavaScriptPython

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-12-30T22:48:35.249Z",
  "updatedAt": "2025-12-30T22:48:35.249Z",
  "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

JWTAuth

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

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

delete

/guardrails/{ruleId}

HTTPcURLJavaScriptPython

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

JWTAuthBasicAuth

AuthorizationstringRequired

JWT authentication token

Body

application/json

Responses

201

Project created successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

500

Internal Server Error

application/json

post

/runners/projects

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

projectIdstringRequired

Unique identifier of the project to retrieve

Responses

200

Project retrieved successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

get

/runners/projects/{projectId}

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

projectIdstringRequired

Unique identifier of the project to update

Body

application/json

Responses

200

Project updated successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

patch

/runners/projects/{projectId}

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

projectIdstringRequired

Unique identifier of the project to delete

Responses

204

Project successfully deleted

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

delete

/runners/projects/{projectId}

HTTPcURLJavaScriptPython

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

JWTAuth

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

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

500

Internal Server Error

application/json

get

/runners/projects/list

HTTPcURLJavaScriptPython

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

JWTAuth

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

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

500

Internal Server Error

application/json

get

/runners/projects/tree

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

projectIdstringRequired

Unique identifier of the project

Responses

200

Members retrieved successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

get

/runners/projects/{projectId}/members

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

projectIdstringRequired

Unique identifier of the project

Bodyobject[]

application/json

userIdstringRequired

ID of the user

rolestring · enumRequired

Role of the user in the project

Possible values:

Responses

201

Members added successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

post

/runners/projects/{projectId}/members

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

projectIdstringRequired

Unique identifier of the project

Bodystring[]

application/json

string[]Optional

User IDs of the members to remove

Responses

204

Members removed successfully

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

delete

/runners/projects/{projectId}/members

HTTPcURLJavaScriptPython

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

JWTAuth

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

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

get

/runners/projects/{projectId}/workspaces

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Responses

200

Project labels retrieved successfully

application/json

Responsestring[]

List of project labels

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

500

Internal Server Error

application/json

get

/runners/projects/labels

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

projectIdstringRequired

Responses

200

List of project variables

application/json

get

/runners/variables/projects/{projectId}

HTTPcURLJavaScriptPython

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-12-30T22:48:35.249Z",
    "updatedAt": "2025-12-30T22:48:35.249Z",
    "sensitivity": "string",
    "destination": "env",
    "origin": "project"
  }
]

Upsert variables within a project (create or update)

post

Authorizations

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

projectIdstringRequired

Body

application/json

Responses

200

Variables upserted within project

application/json

post

/runners/variables/projects/{projectId}/variables

HTTPcURLJavaScriptPython

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-12-30T22:48:35.249Z",
    "updatedAt": "2025-12-30T22:48:35.249Z",
    "sensitivity": "string",
    "destination": "env",
    "origin": "project"
  }
]

Delete variables from a project

delete

Authorizations

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

projectIdstringRequired

Body

application/json

variableKeysstring[] · min: 1Required

Array of variable keys to delete

Responses

204

Variables deleted from project

delete

/runners/variables/projects/{projectId}/variables

HTTPcURLJavaScriptPython

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

JWTAuth

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

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

workspaceIdstringRequired

Body

application/json

Responses

200

Variables upserted within workspace

application/json

post

/runners/variables/workspaces/{workspaceId}/variables

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

workspaceIdstringRequired

Body

application/json

variableIdsstring[] · min: 1Required

Array of variable IDs to delete

Responses

204

Variables deleted from workspace

delete

/runners/variables/workspaces/{workspaceId}/variables

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Query parameters

searchQuerystringOptional

pageSizeintegerOptional

offsetintegerOptional

Responses

200

List of variable sets

application/json

get

/runners/variables/variable-sets

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Body

application/json

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

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

500

Internal Server Error

application/json

post

/runners/variables/variable-sets

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

variableSetIdstringRequired

Responses

200

Variable set

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

500

Internal Server Error

application/json

get

/runners/variables/variable-sets/{variableSetId}

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

variableSetIdstringRequired

Body

application/json

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

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

500

Internal Server Error

application/json

put

/runners/variables/variable-sets/{variableSetId}

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

variableSetIdstringRequired

Responses

204

Variable set deleted successfully

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

500

Internal Server Error

application/json

delete

/runners/variables/variable-sets/{variableSetId}

HTTPcURLJavaScriptPython

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

JWTAuth

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

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

variableSetIdstringRequired

Body

application/json

Responses

200

Variables upserted within variable set

application/json

post

/runners/variables/variable-sets/{variableSetId}/variables

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

variableSetIdstringRequired

Body

application/json

variableIdsstring[] · min: 1Required

Array of variable IDs to delete

Responses

204

Variables deleted from variable set

delete

/runners/variables/variable-sets/{variableSetId}/variables

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

projectIdstringRequired

variableSetIdstringRequired

Body

application/json

consumebooleanRequired

Whether to consume the variable set values

Default: true

Responses

204

Variable set attached to project

post

/runners/variables/projects/{projectId}/variable-sets/{variableSetId}/attach

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

projectIdstringRequired

variableSetIdstringRequired

Responses

204

Variable set detached from project

post

/runners/variables/projects/{projectId}/variable-sets/{variableSetId}/detach

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

workspaceIdstringRequired

variableSetIdstringRequired

Responses

204

Variable set bound to workspace

post

/runners/variables/workspaces/{workspaceId}/variable-sets/{variableSetId}/bind

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

workspaceIdstringRequired

variableSetIdstringRequired

Responses

204

Variable set unbound from workspace

post

/runners/variables/workspaces/{workspaceId}/variable-sets/{variableSetId}/unbind

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Body

application/json

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

201

Workspace created successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

500

Internal Server Error

application/json

post

/runners/workspaces

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Responses

200

Workspace labels retrieved successfully

application/json

Responsestring[]

List of workspace labels

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

500

Internal Server Error

application/json

get

/runners/workspaces/labels

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

workspaceIdstringRequired

Unique identifier of the workspace

Responses

200

Workspace details retrieved successfully

application/json

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

get

/runners/workspaces/{workspaceId}

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

workspaceIdstringRequired

Unique identifier of the workspace

Body

application/json

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

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

post

/runners/workspaces/{workspaceId}

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

workspaceIdstringRequired

Unique identifier of the workspace

Body

application/json

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

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

put

/runners/workspaces/{workspaceId}

HTTPcURLJavaScriptPython

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

JWTAuth

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

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

delete

/runners/workspaces/{workspaceId}

HTTPcURLJavaScriptPython

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

JWTAuth

AuthorizationstringRequired

JWT authentication token

Path parameters

workspaceIdstringRequired

Unique identifier of the workspace

Body

application/json

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

400

Bad Request Error

application/json

401

Unauthorized Error

application/json

403

Insufficient permissions

application/json

404

Not Found Error

application/json

500

Internal Server Error

application/json

post

/runners/workspaces/{workspaceId}/tasks/destroy

HTTPcURLJavaScriptPython

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-12-30T22:48:35.249Z",
  "updatedAt": "2025-12-30T22:48:35.249Z"
}