# Iguana X Web API Reference
This document provides an overview of supported endpoints of the Iguana X Web API.
# `/component/archive_list`
List archived components and report the archive size.
## Parameters
This endpoint does not require any request parameters.
## Example
```lua
local R = iguana.call{api="/component/archive_list", data={}, live=false}
```
## Response
### Success
```json
{
"success": true,
"data": {
"dir": "/path/to/archive",
"components": ["Orders", "Billing"],
"size": "12345"
}
}
```
Notes:
- `dir` is the archive directory path.
- `components` is the list of archived component names.
- `size` is the archive size in bytes.
# `/component/archive_remove`
Remove the archived components directory.
## Parameters
This endpoint does not require any request parameters.
## Permissions
Required permissions:
* Clear Archive
## Example
```lua
local R = iguana.call{api="/component/archive_remove", data={}, live=false}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- Missing `Clear Archive` permission
- The archive directory failed to be removed
# `/component/border/set`
Set the border color for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `color` | string | Yes | - | Border color value to set for the component. |
The `color` parameter can be any legal CSS color value.
## Example
```lua
local R = iguana.call{
api="/component/border/set",
data={
component="Orders",
color="green"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
# `/component/clear_error`
Clear the errors for one or more components.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `components` | array of strings | Yes | - | Component names or ids to clear. |
## Permissions
Required permissions:
* Clear Errors
## Example
```lua
local R = iguana.call{
api="/component/clear_error",
data={
components={"Orders", "Billing"}
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"cleared": ["Orders"],
"skipped": ["Billing"],
"errors": ["No component exists with name or id Billing"]
}
}
```
Notes:
- `cleared` contains the components whose error state was reset.
- `skipped` contains components that could not be found or were not allowed.
- `errors` contains one message per skipped component.
Common errors:
- Missing `Clear Errors` permission
- The `components` field is missing or not formatted as an array of strings
# `/component/clear_queue`
Clear the queue count for one or more components.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `components` | string or array of strings | Yes | - | Component names or ids to clear. |
## Permissions
Required permissions:
* Clear Queue
## Example
```lua
local R = iguana.call{
api="/component/clear_queue",
data={
components={"Orders", "Billing"}
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"cleared": ["Orders"],
"skipped": ["Billing"],
"errors": ["No component exists with name or id Billing"]
}
}
```
Notes:
- `cleared` contains the components whose queue count was reset.
- `skipped` contains components that could not be found or were not allowed.
- `errors` contains one message per skipped component.
Common errors:
- Missing `Clear Queue` permission
- The `components` field is missing or not formatted as a string or array of strings
# `/component/commit_diffs`
Return diff data for files under a component path at a specific commit.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `commit` | string | Yes | - | Commit hash to compare against. |
| `relative_path` | string | Yes | - | Path inside the component to inspect. |
## Example
```lua
local R = iguana.call{
api="/component/commit_diffs",
data={
component="Orders",
commit="a1b2c3d",
relative_path="main.lua"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"main.lua": {
"status": "Files differ.",
"full": {
"from": "...",
"to": "..."
},
"condensed": {
"from": "...",
"to": "..."
},
"summary": {
"added": 1,
"deleted": 0,
"changed": 1
}
}
}
}
```
The response is a map keyed by file name. Each file entry contains the diff payload for that file.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The `component` value does not match an existing component
- The `commit` value is missing or invalid
- The `relative_path` value is missing or invalid
- The commit or path could not be resolved for diff generation
# `/component/commits`
List commits for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
## Example
```lua
local R = iguana.call{
api="/component/commits",
data={
component="Orders"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": [
{
"hash": "a1b2c3d",
"author": "Jane Doe",
"date": "Mon Apr 29 10:00:00 2026 -0400",
"timestamp": "1777461600",
"message": "Update order mapping",
"branch": "main"
}
],
"error" : "Any git error encountered"
}
```
The `error` field is only present if a git error was encountered when fetching the commits.
The `data` field is an array with an entry for each commit.
Commit fields:
- `hash` is the short commit hash.
- `author` is the commit author.
- `date` is the date when the commit was made.
- `timestamp` is the timestamp of the commit.
- `message` is the commit message.
- `branch` is the branch returned by git.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The `component` value does not match an existing component
- The commit history could not be read from git
# `/component/create`
Create one component or a list of components.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `components` | array of component objects | Yes | - | Component objects to create. The structure of each component object is outlined below. |
| `connected` | boolean | No | `false` | If `true`, each component after the first uses the GUID of the previous component as its source. |
| `plain` | boolean | No | `false` | If `true`, create plain folders instead of keeping git template metadata. |
| `source` | string | No | `""` | Source component id or name for the first new component. |
### Component object
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Component name. Must be non-empty, unique, and 60 characters or fewer. |
| `description` | string | No | Component description. |
| `tags` | array of strings | No | Tags for the component. Each string must be in the form `#something`. |
| `git` | string | No | Git URL for the component template. If omitted, the component is treated as blank. |
| `branch` | string | No | Git branch to use. |
| `editable` | boolean | No | If `true`, create the component as editable. |
## Permissions
Required permissions:
* Create Component
* Edit Connections, if `source` is provided
## Example
```lua
local R = iguana.call{
api="/component/create",
data={
components={
{
name="Orders",
description="Orders translator",
tags={"#etl", "#orders"},
git="git@github.com:example/orders.git",
branch="main",
editable=true
}
},
connected=false,
plain=false,
source=""
},
live=false
}
```
## Response
This endpoint returns `200 OK` for both success and error responses.
### Success
```json
{
"success": true,
"data": {
"warning": "optional warning string",
"components": [
{
"run_commit": "a1b2c3d",
"name": "Orders",
"description": "Orders translator",
"guid": "Orders_abc123",
"template": true,
"run_branch": "main",
"run_repo": "git@github.com:example/orders.git",
"run_comp": "",
"tags": [
"etl",
"orders"
],
"fields": {},
"sources": []
}
]
}
}
```
Notes:
- `components` is always an array in the response.
- `run_commit` is trimmed to 7 characters.
- `warning` is present only when the create flow produces one.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- Missing permission.
- `source` does not match an existing component.
- Duplicate component names in the request.
- A component name is empty or longer than 60 characters.
# `/component/delete`
Delete one or more components.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `components` | string or array of strings | Yes | - | Component names or ids to delete. |
## Permissions
Required permissions:
* Delete Component
## Example
```lua
local R = iguana.call{
api="/component/delete",
data={
components={"Orders", "Billing"}
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"removed": [
{
"name": "Orders",
"guid": "Orders_abc123"
}
],
"skipped": [
{
"name": "Billing",
"guid": "Billing_def456"
}
],
"errors": [
"Delete Component permission required to perform this action"
]
}
}
```
Notes:
- `removed` contains components that were queued for deletion.
- `skipped` contains components that were not deleted, including running components and components without permission.
- `errors` contains one message per skipped component.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The `components` input is missing or not formatted correctly
# `/component/description/set`
Set the description for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `value` | string | Yes | - | Description text to store on the component. |
## Permissions
Required permissions:
* Edit Description
## Example
```lua
local R = iguana.call{
api="/component/description/set",
data={
component="Orders",
value="Processes orders from a vendor"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Description` permission
- The updated config could not be saved
# `/component/destinations/allowable`
List the components that can have the current component as a source.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
## Example
```lua
local R = iguana.call{
api="/component/destinations/allowable",
data={
component="Orders"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"destinations": ["Billing", "Shipping"]
}
}
```
The `destinations` array contains component ids that can be selected without creating a cycle.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
# `/component/detail`
Return detailed information for a single component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
## Example
```lua
local R = iguana.call{
api="/component/detail",
data={
component="Orders"
},
live=false
}
```
## Response
A component detail object.
### Success
```json
{
"success": true,
"data": {
"guid": "Orders_abc123",
"commit": "a1b2c3d",
"description": "Orders translator",
"name": "Orders",
"run_branch": "main",
"run_repo": "git@github.com:example/orders.git",
"run_comp": "",
"template": true,
"sources": [],
"tags": ["etl", "orders"],
"initialized": true,
"error_count": 0,
"html_block": "",
"light": "ON",
"queue_count": 0,
"source": "/path/to/component/dev/dir"
}
}
```
Fields:
- `guid` is the component's unique id.
- `commit` is the commit the component is running on.
- `description` contains the component description.
- `name` is the component name.
- `run_branch` is the branch the component is running on.
- `run_repo` is the git repository this component belongs to.
- `run_comp` is which component's development directory is used as the source when creating the run directory.
- `template` reports whether the component is a template.
- `sources` is a list of upstream components that are connected to this one.
- `tags` os a list of tags assigned to the component.
- `initialized` reports whether the component has finished initialization.
- `error_count` is the current component error count.
- `html_block` is the component status HTML block.
- `light` is the component light state as a display string.
- `queue_count` is the current queue count for the component.
- `source` is the component development directory path.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
# `/component/dir`
Read a directory within a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `path` | string | Yes | - | Directory path relative to the component. |
| `development` | boolean | Yes | - | Use `true` for development repos, `false` for run repos. |
| `exclude` | object | No | `{}` | Map of file extensions to exclude from the listing. |
## Permissions
Required permissions:
* View Script, when `development` is `false`
* Edit Script, when `development` is `true`
## Example
```lua
local R = iguana.call{
api="/component/dir",
data={
component="Orders",
path="scripts/",
development=true,
exclude={
tmp=true
}
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"component": "Orders",
"exists": true,
"dir": true,
"content": [
{
"name": "main.lua",
"dir": false
},
{
"name": "lib",
"dir": true
}
]
}
}
```
If the path does not exist:
```json
{
"success": true,
"data": {
"component": "Orders",
"exists": false
}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- Missing `View Script` permission when `development` is `false`, or `Edit Script` permission when `development` is `true`
- The component name or id was not found
- The path could not be resolved within the component
# `/component/dir/add`
Create a directory within a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `path` | string | Yes | - | Directory path relative to the component. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/dir/add",
data={
component="Orders",
path="scripts/lib/",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- A directory with the same name already exists
- The directory path is invalid
# `/component/dir/delete`
Delete a directory within a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `path` | string | Yes | - | Directory path relative to the component. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/dir/delete",
data={
component="Orders",
path="scripts/lib/",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- The path could not be resolved within the component
- The directory does not exist
- The path points to a file instead of a directory
# `/component/dir/rename`
Rename or move a directory within a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `old_path` | string | Yes | - | Current directory path relative to the component. |
| `new_path` | string | Yes | - | New directory path relative to the component. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/dir/rename",
data={
component="Orders",
old_path="scripts/lib/",
new_path="scripts/core/",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- The original directory no longer exists
- A file or folder with the new name already exists
- The new directory name is invalid
- The path could not be resolved within the component
# `/component/edit/tags`
Add and remove tags on one or more components.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `components` | array of strings | Yes | - | Component names or ids to update. |
| `add` | string | No | `""` | Space-separated list of tags to add. Each tag must be in the form `#something`. |
| `remove` | string | No | `""` | Space-separated list of tags to remove. Each tag must be in the form `#something`. |
Hashtags can only include letters, numbers, and underscores (a–z, A–Z, 0–9, and _).
## Permissions
Required permissions:
* Edit Description
## Example
```lua
local R = iguana.call{
api="/component/edit/tags",
data={
components={"Orders", "Billing"},
add="#etl #nightly",
remove="#old"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
If all component updates succeed, the request returns success with an empty body. The edit process is terminated on first error.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The `components` field is missing or not an array
- One of the component names or ids was not found
- Missing `Edit Description` permission
- One or more tags do not match the required `#something` format
- The component configuration could not be saved
# `/component/fetch_repositories`
Fetch and refresh repositories and commits for a component and its libraries.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
The request starts a background refresh for the component's main repository and any libraries listed in `.gitmodules`.
## Permissions
None.
## Example
```lua
local R = iguana.call{
api="/component/fetch_repositories",
data={
component="Orders"
},
live=false
}
```
## Response
### Success
When the fetch is successfully started, an empty success message is returned.
```json
{
"success": true,
"data": {}
}
```
There may already be a refresh job in progress. In such cases, a busy response is returned.
```json
{
"success": true,
"data": {
"busy": true,
"message": "Repository refresh already in progress."
}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- The component repository does not exist
- A repository refresh is already in progress
# `/component/field/grammar`
Return the custom field grammar for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `development` | boolean | Yes | - | Use `true` for the development tree, or `false` for the run tree. |
## Permissions
Required permissions:
* Edit Fields
## Example
```lua
local R = iguana.call{
api="/component/field/grammar",
data={
component="Orders",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": [
{
"name": "host",
"default": "localhost",
"type": "String",
"options": [],
"description": "Database host"
}
]
}
```
Each entry in `data` describes one custom field in `config.json`. Each field has the following parameters
- `name` is the field name.
- `default` is the default value stored in the grammar.
- `type` is the field type as a display string.
- `options` contains any field options parsed from the grammar.
- `description` is included when the grammar defines one.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Fields` permission
- The field grammar file could not be parsed
# `/component/field/grammar/set`
Save a custom field grammar for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `name` | string | Yes | - | Grammar name. This is required by the handler for compatibility, but it is not used. |
| `fields` | array of objects | Yes | - | Custom field definitions to save. |
| `development` | boolean | Yes | - | Use `true` to save to the development tree, or `false` to save to the run tree. |
Field object structure:
| Field | Type | Description |
| --- | --- | --- |
| `name` | string | Field name. |
| `type` | string | Field type, such as `string`, `number`, `bool`, `password`, `file`, `folder`, `port`, or `list`. |
| `default` | string | Default value for the field. |
| `options` | string | Optional comma-separated list of allowed values. |
| `description` | string | Optional helper text for the field. |
## Permissions
Required permissions:
* Edit Fields
## Example
```lua
local R = iguana.call{
api="/component/field/grammar/set",
data={
component="Orders",
name="config",
fields={
{
name="host",
type="string",
default="localhost",
description="Database host"
}
},
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Fields` permission
- The `fields` value is not an array of field definitions
- A field definition is invalid
- The field grammar could not be validated
- The grammar could not be saved
# `/component/fields/get`
Return the current values for a component's custom fields.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
## Permissions
Required permissions:
* View Script
## Example
```lua
local R = iguana.call{
api="/component/fields/get",
data={
component="Orders"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": [
{
"name": "host",
"default": "localhost",
"type": "String",
"options": [],
"description": "Database host",
"true_value": "db.internal",
"display_value": "db.internal"
}
]
}
```
Each field entry includes the grammar metadata and the current value.
Fields:
- `true_value` is the stored value.
- `display_value` is the value shown after environment expansion.
- Password fields are masked in the response.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `View Script` permission
- The field grammar could not be loaded
# `/component/fields/set`
Update a custom field value for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `name` | string | Yes | - | Field name to update. |
| `value` | string | Yes | - | New field value. |
## Permissions
Required permissions:
* Edit Fields
## Example
```lua
local R = iguana.call{
api="/component/fields/set",
data={
component="Orders",
name="host",
value="db.internal"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
The updated value is validated against the component's field grammar before it is saved.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Fields` permission
- The field name is not defined in the grammar
- The field value is invalid for the declared type
- The field grammar could not be loaded
- The component configuration could not be saved
# `/component/file`
Read a file or inspect a directory within a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `path` | string | Yes | - | Path relative to the component. |
| `development` | boolean | Yes | - | Use `true` for development repos, `false` for run repos. |
## Permissions
Required permissions:
* View Script, when `development` is `false`
* Edit Script, when `development` is `true`
## Example
```lua
local R = iguana.call{
api="/component/file",
data={
component="Orders",
path="main.lua",
development=true
},
live=false
}
```
## Response
### Success
If the path points to a file:
```json
{
"success": true,
"data": {
"exists": true,
"dir": false,
"content": "-- file contents"
}
}
```
If the path points to a directory:
```json
{
"success": true,
"data": {
"exists": true,
"dir": true
}
}
```
If the path does not exist:
```json
{
"success": true,
"data": {
"exists": false
}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- Missing `View Script` permission when `development` is `false`, or `Edit Script` permission when `development` is `true`
- The component name or id was not found
- The path could not be resolved within the component
# `/component/file/add`
Create a new file in a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `path` | string | Yes | - | Path of the new file relative to the component. |
| `content` | string | Yes | - | File content to write. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/file/add",
data={
component="Orders",
path="scripts/new_file.lua",
content="print('hello')",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- The path could not be resolved within the component
- A file or folder with the same name already exists
- The path is invalid
# `/component/file/delete`
Delete a file from a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `path` | string | Yes | - | Path of the file relative to the component. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/file/delete",
data={
component="Orders",
path="scripts/new_file.lua",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- The path could not be resolved within the component
- The file does not exist
- The path points to a directory instead of a file
# `/component/file/rename`
Rename or move a file within a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `old_path` | string | Yes | - | Current file path relative to the component. |
| `new_path` | string | Yes | - | New file path relative to the component. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/file/rename",
data={
component="Orders",
old_path="scripts/old.lua",
new_path="scripts/new.lua",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- The original file no longer exists
- A file or folder with the new name already exists
- The new file name is invalid
- The path could not be resolved within the component
# `/component/file/upload`
Upload a file into a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `path` | string | Yes | - | File path relative to the component. |
| `content` | string | Yes | - | File contents to write. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/file/upload",
data={
component="Orders",
path="scripts/new_file.lua",
content="print('hello')",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
If the file is uploaded under a `Samples/` path, the content may be treated as sample-encoded input and decoded before it is written.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- The path could not be resolved within the component
- The file extension is not allowed
- A file or folder with this name already exists
# `/component/get_repository`
Return repository details for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `development` | boolean | Yes | - | Set to `true` to inspect the development tree (current code), or `false` to inspect the run tree (code on a commit as executed). |
| `path` | string | No | `""` | Optional path inside the component. Used when resolving a repository under a module path. |
## Permissions
None.
## Example
```lua
local R = iguana.call{
api="/component/get_repository",
data={
component="Orders",
development=false,
path="lib/orders"
},
live=false
}
```
## Response
A repository summary object.
### Success
```json
{
"success": true,
"data": {
"repo": "git@github.com:example/orders.git",
"branch": "main",
"default_branch": "main",
"link": "https://github.com/example/orders/tree/main",
"urls": {
"web": "https://github.com/example/orders/tree/main"
}
}
}
```
Possible response fields:
- `repo` is the resolved repository URL.
- `branch` is the current branch for the selected tree.
- `default_branch` is the repository default branch.
- `link` is the web link for the repository and branch, when one can be built.
- `urls` contains the link variants returned by the repository link builder.
- `plain` is `true` when the development tree is a plain folder instead of a git repository.
- `error` may be present when the repository URL is known but a link could not be built.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- The `development` value is missing or invalid
# `/component/git_ahead_behind`
Return ahead/behind status for a component and its modules.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `development` | boolean | Yes | - | Use `true` for the development tree, or `false` for the run tree. |
## Permissions
Required permissions:
* View Script, when `development` is `false`
* Edit Script, when `development` is `true`
## Example
```lua
local R = iguana.call{
api="/component/git_ahead_behind",
data={
component="Orders",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"Orders": {
"correct_repo": true,
"can_push": false,
"can_pull": true,
"initialized": true
}
}
}
```
The response is a map keyed by component/module path. Each entry describes the git state for that repository.
Fields:
- `correct_repo` is `true` when the repository remote matches the component's configured repository.
- `can_push` is `true` when the local repository is ahead of its upstream.
- `can_pull` is `true` when the local repository is behind its upstream.
- `initialized` is `true` when the repository exists and has a `.git` directory.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `View Script` permission when `development` is `false`, or `Edit Script` permission when `development` is `true`
# `/component/git_history`
Return the git commit history for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `development` | boolean | Yes | - | Use `true` to inspect the development tree, or `false` to inspect the run tree. |
| `path` | string | No | `""` | Optional path inside the component. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/git_history",
data={
component="Orders",
development=true,
path=""
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"path": "/path/to/component/dev",
"commits": {
"1777461600a1b2c3d": {
"hash": "a1b2c3d",
"author": "Jane Doe",
"date": "Mon Apr 29 10:00:00 2026 -0400",
"timestamp": "1777461600",
"message": "Update order mapping",
"branch": "main",
"path": ""
}
}
}
}
```
The `commits` object is keyed by a timestamp/hash composite to keep entries unique.
Commit fields:
- `hash` is the short commit hash.
- `author` is the commit author.
- `date` is the git date string.
- `timestamp` is the commit timestamp.
- `message` is the commit message.
- `branch` is the branch reported by git.
- `path` is the component path that was inspected.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Script` permission
# `/component/ide/commit/info`
Return the current commit information for a component's development or run tree.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `development` | boolean | Yes | - | Set to `true` to read the development tree, or `false` to read the run tree. |
## Permissions
None.
## Example
```lua
local R = iguana.call{
api="/component/ide/commit/info",
data={
component="Orders",
development=true
},
live=false
}
```
## Response
Commit information for the selected repository directory.
### Success
```json
{
"success": true,
"data": {
"commit": "a1b2c3d",
"author": "Jane Doe",
"time_stamp": "2 days ago",
"message": "Update order mapping",
"branch": "main"
}
}
```
Fields:
- `commit` is the short commit hash.
- `author` is the commit author.
- `time_stamp` is the relative commit time.
- `message` is the commit message.
- `branch` is the current branch for the selected tree.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- The `development` value is missing or invalid
# `/component/library/add`
Add an existing library into a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `name` | string | Yes | - | Library name. Must contain only uppercase letters and numbers. |
| `git` | string | Yes | - | Git URL for the library. |
| `plain` | boolean | No | `false` | When `true`, add the library as a plain folder instead of a git submodule. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/library/add",
data={
component="Orders",
name="UTILS",
git="git@github.com:example/utils.git",
plain=false,
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- The library name is empty or contains invalid characters
- A folder or file already exists with the same library name
- The library could not be found in cache or could not be cloned to cache
- The component is plain and the library was not added as a plain folder
# `/component/library/create`
Create a new library inside a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `name` | string | Yes | - | Library name. Must contain only uppercase letters and numbers. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/library/create",
data={
component="Orders",
name="UTILS",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- The component is plain and cannot host a git-backed library
- The library name is empty or contains invalid characters
- The library could not be created
# `/component/library/delete`
Delete a library from a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `name` | string | Yes | - | Library name to delete. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/library/delete",
data={
component="Orders",
name="UTILS",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- No folder exists with the given library name
- The library directory could not be removed
# `/component/library/initialize`
Initialize a single library inside a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `module_name` | string | Yes | - | Name of the library module to initialize. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/library/initialize",
data={
component="Orders",
module_name="UTILS",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- The `.gitmodules` file could not be found
- The library module was not found in `.gitmodules`
- The library could not be initialized
# `/component/library/initialize/all`
Initialize all libraries for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `commit_id` | string | No | `""` | Optional commit id for the component. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/library/initialize/all",
data={
component="Orders",
commit_id="",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- One or more libraries could not be initialized
# `/component/library/list`
List the libraries in a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `development` | boolean | Yes | - | Use `true` for the development tree, or `false` for the run tree. |
## Permissions
Required permissions:
* View Script, when `development` is `false`
* Edit Script, when `development` is `true`
## Example
```lua
local R = iguana.call{
api="/component/library/list",
data={
component="Orders",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"UTILS": {
"url": "git@github.com:example/utils.git",
"locked": false,
"git": {
"web": "https://github.com/example/utils/branches",
"web_branch": "https://github.com/example/utils/tree/main",
"url": "https://github.com/example/utils.git",
"ssh": "git@github.com:example/utils.git"
}
}
}
}
```
`data` is a map keyed by library name listing details about that library. If the component has no `.gitmodules` file, the response is an empty object.
Fields:
- `url` is the library's git URL.
- `locked` is `true` when the URL is an `httpx`-style locked URL.
- `git` contains repository links for the library.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `View Script` permission when `development` is `false`, or `Edit Script` permission when `development` is `true`
# `/component/library/remote/remove`
Remove the upstream remote for a library.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `name` | string | Yes | - | Library name. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/library/remote/remove",
data={
component="Orders",
name="UTILS",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- The library path could not be resolved
- The remote could not be removed from the library
# `/component/library/rename`
Rename a library inside a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `library` | string | Yes | - | Current library name. |
| `rename` | string | Yes | - | New library name. Must contain only uppercase letters and numbers. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/library/rename",
data={
component="Orders",
library="UTILS",
rename="COMMON",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- The current library folder was not found
- The target library name already exists
- The new library name is invalid
- The rename could not be completed
# `/component/library/rename/content`
Rename files inside a library and update references to the library name.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `old_name` | string | Yes | - | Current library name. |
| `new_name` | string | Yes | - | New library name. |
| `path` | string | Yes | - | Library path inside the component. |
| `development` | boolean | Yes | - | Must be `true`. File structure changes are not allowed in run repositories. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/library/rename/content",
data={
component="Orders",
old_name="UTILS",
new_name="COMMON",
path="UTILS",
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- File structure changes are not allowed in a run repository
- Missing `Edit Script` permission
- The component name or id was not found
- The library path could not be resolved
- One or more files could not be renamed
- The content search and replace failed
# `/component/library/set_upstream`
Set or update the upstream repository for a library.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `name` | string | Yes | - | Library name. |
| `git` | string | Yes | - | Git URL for the upstream repository. |
| `push` | boolean | No | `false` | When `true`, push the library after setting the remote. |
| `development` | boolean | Yes | - | Must be `true`. Libraries in run repositories cannot be modified. |
## Permissions
Required permissions:
* Edit Script
## Example
```lua
local R = iguana.call{
api="/component/library/set_upstream",
data={
component="Orders",
name="UTILS",
git="git@github.com:example/utils.git",
push=false,
development=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- Libraries in run repositories cannot be modified
- Missing `Edit Script` permission
- The component name or id was not found
- The library is inside a plain component
- The git URL could not be parsed
- The remote could not be added
- Pushing the library failed
# `/component/list`
List components and return their dashboard data.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `filter` | string | No | `""` | Filter terms used to match component names. |
| `order` | string | No | `"NAME"` | Sort order to use for the returned list. |
| `checked` | object | No | `{}` | Map of checked component names. |
| `whole_word` | boolean | No | `false` | If `true`, filter matches are exact terms. |
| `checked_only` | boolean | No | `false` | If `true`, only components in `checked` are returned. |
| `ascending` | boolean | No | `true` | If `true`, sort in ascending order. |
The possible values for `order` are `RUN`, `ERR`, `QUE`, `SERVER`, `NAME`, `LAST`, `IN`, `OUT` or `ACT`.
## Example
```lua
local R = iguana.call{
api="/component/list",
data={
filter="Orders",
order="NAME",
checked={
Orders=true
},
whole_word=false,
checked_only=false,
ascending=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"component_data": [
{
"role": {},
"guid": "Orders_abc123",
"commit": "a1b2c3d",
"description": "Orders translator",
"name": "Orders",
"template": true,
"tags": ["etl", "orders"],
"host_server_guid": "server-1",
"error_count": 0,
"tooltip": "",
"light": "ON",
"queue_count": 0,
"mps_in": 0,
"mps_out": 0,
"last_activity": "0",
"columns": {}
}
],
"total_components": 5
}
}
```
Fields:
- `component_data` contains the component rows after filtering, selection, and sorting.
- Each row lists the dashboard fields for a single component such as role, queue count, activity, and light state.
- `total_components` is the total number of components in the instance, not just the returned rows.
# `/component/make_editable`
Convert a repository component so it can be edited.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `edit_original` | boolean | No | `false` | When `true`, convert the original remote from HTTPS to SSH. When `false`, remove the remote from the editable copy. |
## Permissions
Required permissions:
* Edit Upstream
## Example
```lua
local R = iguana.call{
api="/component/make_editable",
data={
component="Orders",
edit_original=false
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"new_git": "git@github.com:example/orders.git"
}
}
```
If `edit_original` is `false`, the response may include `old_git` instead of `new_git`.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Upstream` permission
- The repository could not be prepared for editing
- The component config could not be loaded or saved
- Repository cleanup or library reset failed
# `/component/map`
Return graph data for the selected components.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `filter` | string | No | `""` | Text filter used to match component names and tags. |
| `checked` | array of strings | No | `[]` | List of checked component ids. |
| `whole_word` | boolean | No | `false` | Match the filter as a whole word. |
| `group` | boolean | No | `true` | When `true`, use the `checked` list as the selected set. |
| `checked_only` | boolean | No | `false` | When `true`, return only the checked components. |
## Permissions
None.
## Example
```lua
local R = iguana.call{
api="/component/map",
data={
filter="orders",
checked={"Orders"},
whole_word=false,
group=true,
checked_only=true
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"Orders": {
"guid": "Orders",
"name": "Orders",
"template": true,
"border": "",
"tooltip": "",
"light": "ON",
"error_count": 0,
"queue_count": 0,
"tags": ["#orders"],
"sources": ["Billing"],
"receivers": ["Shipping"],
"group": false,
"type": "node"
}
}
}
```
The response is a map keyed by component id. Each entry contains the component data used by the dashboard graph.
No error response is returned by this handler.
# `/component/names`
List the names of all components.
## Parameters
This endpoint does not require any request parameters.
## Example
```lua
local R = iguana.call{api="/component/names", data={}, live=false}
```
## Response
Returns a `data` object with a map of component names set to `true`.
### Success
```json
{
"success": true,
"data": {
"Orders": true,
"Billing": true
}
}
```
# `/component/name/set`
Set the name for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `value` | string | Yes | - | New component name. |
## Permissions
Required permissions:
* Edit Name
## Example
```lua
local R = iguana.call{
api="/component/name/set",
data={
component="Orders",
value="Orders v2"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Name` permission
- The new name is empty
- The new name is longer than 60 characters
- Another component already uses the same name
- The updated config could not be saved
# `/component/permission`
Return the permissions the user has for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | No | `""` | Component name or id. If omitted, the check uses the base Iguana permission set. |
## Permissions
None.
## Example
```lua
local R = iguana.call{
api="/component/permission",
data={
component="Orders"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"change_log_folder": true,
"clear_archive": false,
...
}
}
```
The `data` object is a map of permissions, where each entry represents a specific permission and is set to `true` or `false` depending on whether the requesting user has that permission.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Permissions could not be resolved for the requested component
# `/component/permission/all`
Return the permissions the user has for all components.
## Parameters
None.
## Permissions
None.
## Example
```lua
local R = iguana.call{api="/component/permission/all", data={}, live=false}
```
## Response
### Success
```json
{
"success": true,
"data": {
"components": {
"Orders": {
"permission": true
},
"Billing": {
"permission": false
}
},
"errors": [
"Billing: Permissions could not be resolved"
]
}
}
```
The `components` object is keyed by component id. Each entry inside a component id represents a specific permission and is set to `true` or `false` depending on whether the requesting user has that permission.
If permission resolution fails for a component, it is reported in `errors` instead of failing the whole request.
# `/component/remove_upstream`
Remove the upstream git repository from a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
## Permissions
Required permissions:
* Edit Upstream
## Example
```lua
local R = iguana.call{
api="/component/remove_upstream",
data={
component="Orders"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"old_git": "git@github.com:example/orders.git"
}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Upstream` permission
# `/component/run_list`
List the components that are currently running.
## Parameters
This endpoint does not require any request parameters.
## Example
```lua
local R = iguana.call{api="/component/run_list", data={}, live=false}
```
## Response
### Success
```json
{
"success": true,
"data": {
"Orders_abc123": true,
"Billing_def456": true
}
}
```
The response is a map of running component ids to `true`.
# `/component/set_branch`
Set the active branch for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `branch` | string | Yes | - | Branch name to switch to or create. |
| `development` | boolean | Yes | - | Must be `true`. Run repositories cannot be modified. |
| `allow_existing` | boolean | No | `false` | If `true`, switch to an existing local branch without prompting. |
## Permissions
Required permissions:
* Edit Upstream
## Example
```lua
local R = iguana.call{
api="/component/set_branch",
data={
component="Orders",
branch="release/v2",
development=true,
allow_existing=false
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"old_branch": "main",
"branch": "release/v2",
"created": true
}
}
```
Notes:
- `created` is `true` when the branch was created and `false` when the component switched to an existing branch.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Upstream` permission
- File structure changes are not allowed in a run repository
- The branch name is invalid
- The branch already exists and `allow_existing` is `false`
- The branch could not be created or checked out
- Pushing the new branch failed
# `/component/set_commit`
Set the commit used by a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `commit` | string | Yes | - | Commit hash or `DEVELOPMENT`. |
| `run_comp` | string | No | `""` | Run source component id to use when building the run directory. |
## Permissions
Required permissions:
* Edit Commit
* View Script on `run_comp`, if `run_comp` is provided
## Example
```lua
local R = iguana.call{
api="/component/set_commit",
data={
component="Orders",
commit="a1b2c3d",
run_comp=""
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": ""
}
```
If the operation produces a warning, it is returned as the response data string.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Commit` permission
- The `run_comp` component was not found
- Missing `View Script` access on `run_comp`
- The commit cannot be switched to development for a template component
- The run directory could not be removed or created
- The config file could not be parsed or saved
# `/component/set_upstream`
Set the upstream git repository for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `development` | boolean | Yes | - | Must be `true`. Run repositories cannot be modified. |
| `git` | string | Yes | - | Upstream git URL. |
| `push` | boolean | No | `false` | If `true`, push the current branch after setting the remote. |
## Permissions
Required permissions:
* Edit Upstream
## Example
```lua
local R = iguana.call{
api="/component/set_upstream",
data={
component="Orders",
development=true,
git="git@github.com:example/orders.git",
push=false
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"git": "git@github.com:example/orders.git"
}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Upstream` permission
- File structure changes are not allowed in a run repository
- The git URL could not be parsed
- The upstream remote could not be set
- Pushing the branch failed
# `/component/source/add`
Add a source connection between two components.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Destination component name or id. |
| `source` | string | Yes | - | Source component name or id. |
## Permissions
Required permissions:
* Edit Connections on the destination component
* Edit Connections on the source component
## Example
```lua
local R = iguana.call{
api="/component/source/add",
data={
component="Orders",
source="Billing"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
Notes:
- If the source already exists or is the same as the destination, the request succeeds without making a change.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The destination component is not found
- The source component is not found
- Missing `Edit Connections` permission on the destination or source component
- The destination component is still running
- Adding the source component would create a cycle
# `/component/source/delete`
Remove a source connection from a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Destination component name or id. |
| `remove_source` | string | Yes | - | Source component name or id to remove. |
## Permissions
Required permissions:
* Edit Connections on the destination component
* Edit Connections on the source component
## Example
```lua
local R = iguana.call{
api="/component/source/delete",
data={
component="Orders",
remove_source="Billing"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The destination component is not found
- The source component is not found
- Missing `Edit Connections` permission on the destination or source component
- The destination component must be stopped before changing connections
# `/component/sources/allowable`
List the source components that can be connected to the specified component without creating a cycle.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
## Example
```lua
local R = iguana.call{
api="/component/sources/allowable",
data={
component="Orders"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"sources": ["Billing", "Shipping"]
}
}
```
The `sources` array contains component ids that can be added as sources without introducing a cycle.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
# `/component/start`
Request one or more components to start. The start operation is performed asynchronously. To track progress, set the `tracked` flag in the request, capture the `job_id` from the response, and use `component/start/check` to monitor the job status.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `components` | string or array of strings | Yes | - | Component names or ids to start. |
| `tracked` | boolean | No | `false` | If `true`, the start job stays available for `/component/start/check` after it finishes. |
## Permissions
Required permissions:
* Start Component
Each component in the request is checked individually.
## Example
```lua
local R = iguana.call{
api="/component/start",
data={
components={"Orders", "Billing"},
tracked=true
},
live=false
}
```
## Response
This response shows that the Orders component has been requested to start, while the Billing component did not receive a start request due to a permission error.
### Success
```json
{
"success": true,
"data": {
"switched": ["Orders"],
"skipped": ["Billing"],
"errors": ["Start Component permission required to perform this action"],
"job_id": "abc123"
}
}
```
Notes:
- `switched` contains the components that were accepted for startup.
- `skipped` contains the components that were not started.
- `errors` contains one message per skipped component.
- `job_id` is present only when at least one component is started asynchronously.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- License limit hit for number of components that can be running
- The `components` input is not formatted correctly
# `/component/start/check`
Check the status of a component start job.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `job_id` | string | Yes | - | The start job id returned by `/component/start`. |
## Example
```lua
local R = iguana.call{
api="/component/start/check",
data={
job_id="abc123"
},
live=false
}
```
## Response
### Success
When the job is still running:
```json
{
"success": true,
"data": {
"running": true
}
}
```
When the job has finished successfully:
```json
{
"success": true,
"data": {
"running": false
}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- No component start job found.
- The start job finished with an error, in which case the error message is returned with a note to see the Iguana Service logs for more details.
# `/component/status/set`
Set the HTML status block for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `html` | string | Yes | - | HTML status block to store on the component. |
## Example
```lua
local R = iguana.call{
api="/component/status/set",
data={
component="Orders",
html="Running normally
"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
# `/component/stop`
Stop one component or a list of components.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `components` | string or array of strings | Yes | - | Component names or ids to stop. |
| `tracked` | boolean | No | `false` | If `true`, the stop job stays available for `/component/stop/check` after it finishes. |
| `force` | boolean | No | `false` | If `true`, force the component to stop. |
## Permissions
Required permissions:
* Stop Component
Each component in the request is checked individually.
## Example
```lua
local R = iguana.call{
api="/component/stop",
data={
components={"Orders", "Billing"},
force=false,
tracked=true
},
live=false
}
```
## Response
This response shows that the Orders component has been requested to stop, while the Billing component did not receive a stop request due to a permission error.
```json
{
"success": true,
"data": {
"switched": ["Orders"],
"skipped": ["Billing"],
"errors": ["Stop Component permission required to perform this action"],
"job_id": "abc123"
}
}
```
Notes:
- `switched` contains the components that were accepted for shutdown.
- `skipped` contains the components that were not stopped.
- `errors` contains one message per skipped component.
- `job_id` is present only when at least one component is stopped asynchronously.
# `/component/stop/check`
Check the status of a component stop job.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `job_id` | string | Yes | - | The stop job id returned by `/component/stop`. |
## Permissions
Required permissions:
* Stop Component
## Example
```lua
local R = iguana.call{
api="/component/stop/check",
data={
job_id="abc123"
},
live=false
}
```
## Response
### Success
When the job is still running:
```json
{
"success": true,
"data": {
"running": true
}
}
```
When the job has finished successfully:
```json
{
"success": true,
"data": {
"running": false
}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- No component stop job found.
- The stop job finished with an error, in which case the error message is returned with a note to see the Iguana Service logs for more details.
# `/component/tags/set`
Replace the full tag list for a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `value` | array of strings | Yes | - | The new tag list. Each tag must be in the form `#something`. |
Hashtags can only include letters, numbers, and underscores (a–z, A–Z, 0–9, and _).
## Permissions
Required permissions:
* Edit Tags
## Example
```lua
local R = iguana.call{
api="/component/tags/set",
data={
component="Orders",
value={"#etl", "#orders"}
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Tags` permission
- The `value` field is not an array of valid tag strings
- One or more tags do not match the required `#something` format
# `/component/tooltip/set`
Set the tooltip that is displayed on hover of a component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
| `html` | string | Yes | - | HTML content for the tooltip block. |
## Permissions
None.
## Example
```lua
local R = iguana.call{
api="/component/tooltip/set",
data={
component="Orders",
html="Orders translator
"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
# `/component/turn_plain`
Convert a repository component into a plain component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
## Permissions
Required permissions:
* Edit Upstream
## Example
```lua
local R = iguana.call{
api="/component/turn_plain",
data={
component="Orders"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
The component is updated to `DEVELOPMENT`, its run repository fields are cleared, and the component is re-registered after the conversion.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- The component is currently running
- Missing `Edit Upstream` permission
- The repository cleanup or conversion failed
# `/component/turn_repo`
Convert a plain component into a git repository component.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | Yes | - | Component name or id. |
## Permissions
Required permissions:
* Edit Script
* Edit Upstream
## Example
```lua
local R = iguana.call{
api="/component/turn_repo",
data={
component="Orders"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
The component is copied into a scratch git repository, committed, and then moved back into place as a repository-backed component.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `Edit Script` permission
- Missing `Edit Upstream` permission
- The component is currently running
- The repository could not be initialized or committed
- The component files could not be copied or restored
# `/log/detail`
Return a single log message, with optional chunk rendering.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | No | `""` | Component name or id. If omitted, the `Iguana Service` logs are queried. |
| `id` | integer | Yes | - | Message index. |
| `time` | integer | Yes | - | Message timestamp in milliseconds. |
| `chunk` | integer | No | `0` | Starting chunk index. |
| `chunk_extra` | integer | No | `0` | Additional chunks to include. |
| `view_mode` | string | No | `""` | Chunk rendering mode. |
| `raw` | boolean | No | `false` | When `true`, return the raw message body. |
| `filter` | string | No | `""` | Search filter used by the detail renderer. |
The `component`, `id` and `time` parameters are used to uniquely identify a log message. To ensure a valid combination, first use the `/logs/retrieve` API to get a list of messages for the component and parse the response for the message you want the full details on.
## Permissions
Required permissions:
* View Logs
## Example
```lua
local R = iguana.call{
component.runAsUser{user="admin"}
api="/log/detail",
data={
component="Orders",
id=12,
time=1777461600000,
chunk=0,
chunk_extra=0,
view_mode="plain",
raw=false,
filter=""
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {
"file": "/path/to/log/file",
"component": "Orders",
"type": "error",
"time": "1777461600000",
"id": "12",
"size": "84",
"comp": "Orders",
"rel_comp": "",
"rel_time": "0",
"rel_id": "0",
"sid": "12",
"qid": "5",
"tags": ["#error"],
"content": "..."
}
}
```
If `raw` is `false`, the response includes chunk-rendered content. If `raw` is `true`, `content` contains the unmodified message body.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `View Logs` permission
- The message could not be found
- The requested chunk values are invalid
# `/log/detail/search/poll`
Return the current results for a running detail search.
## Parameters
None.
The endpoint uses the current user to look up the active search.
## Permissions
None.
## Example
```lua
component.runAsUser{user="admin"}
local R = iguana.call{api="/log/detail/search/poll", data={}, live=false}
```
## Response
### Success
```json
{
"success": true,
"data": {
"search": [
{
"Value": "matched text"
}
],
"count": "3",
"done": false
}
}
```
Fields:
- `search` contains the accumulated matching chunks.
- `count` is the number of matches found so far.
- `done` is `true` when the search has finished.
# `/log/detail/search/start`
Start a search inside a single log message.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | No | `""` | Component name or id. If omitted, the service log component is used. |
| `id` | integer | Yes | - | Message index. |
| `time` | integer | Yes | - | Message timestamp in milliseconds. |
| `search` | string | No | `""` | Text to search for inside the message. |
| `chunk` | integer | No | `0` | Starting chunk index. |
| `view_mode` | string | No | `""` | Search is only supported in plain text or escaped text view. |
Only one log detail search job per user can be active at a time.
## Permissions
Required permissions:
* View Logs
## Example
```lua
local R = iguana.call{
component.runAsUser{user="admin"}
api="/log/detail/search/start",
data={
component="Orders",
id=12,
time=1777461600000,
search="error",
chunk=0,
view_mode="plain"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
The search runs in the background. Poll `/log/detail/search/poll` to read the results.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `View Logs` permission
- Searching is only supported in plain or escaped text view
# `/logs/retrieve`
Search component logs and return matching entries, either synchronously or asynchronously.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | string | No | `""` | Component name or id. If omitted, the `Iguana Service` logs are queried. |
| `limit` | integer | No | `20` | Maximum number of log entries to return. |
| `search` | string | No | `""` | Text to search for in log messages. |
| `tags` | string | No | `""` | Tag filter such as `#error` or `#message`. |
| `include_non_matches` | boolean | No | `false` | When `true`, return non-matching entries too. |
| `formatted` | boolean | No | `false` | When `true`, add markup to matched text. |
| `minify` | boolean | No | `false` | When `true`, omit the log content body. |
| `relevant` | boolean | No | `false` | When `true`, narrow the result window to 24 hours around the first match. |
| `job` | string | No | `""` | Asynchronous job id. When provided, the request starts or replaces a background job. |
| `critical` | boolean | No | `true` | When `false`, the request times out after a short period. |
| `exact` | boolean | No | `false` | Match search terms exactly. |
| `forward` | boolean | No | `false` | Search forward instead of backward. |
| `exclusive` | boolean | No | `false` | Exclude boundary messages from the search window. |
| `only_messages` | boolean | No | `false` | Restrict the search to message entries. |
| `start` | string | No | `"0"` | Start timestamp in milliseconds. |
| `end` | string | No | `"0"` | End timestamp in milliseconds. |
| `start_id` | string | No | `"0"` | Start message index. |
| `end_id` | string | No | `"0"` | End message index. |
| `rel_comp` | string | No | `""` | Related component id. |
| `rel_time` | string | No | `"0"` | Related message timestamp in milliseconds. |
| `rel_id` | string | No | `"0"` | Related message index. |
## Permissions
Required permissions:
* View Logs
## Example
```lua
local R = iguana.call{
component.runAsUser{user="admin"}
api="/logs/retrieve",
data={
component="Orders",
limit=40,
search="error",
tags="#error",
formatted=false,
job=""
},
live=false
}
```
## Response
### Success
Synchronous search:
```json
{
"success": true,
"data": [
{
"type": "error",
"time": "1777461600000",
"id": "12",
"size": "84",
"comp": "Orders",
"rel_comp": "",
"rel_time": "0",
"rel_id": "0",
"sid": "12",
"qid": "5",
"tags": ["#error"],
"match": true,
"content": "This message included the word error as filtered"
}
]
}
```
Each log entry includes the log metadata fields returned by the logger, plus `match`. When `formatted` is `true`, `content` may contain highlighted markup.
For an asynchronous search start, only a simple sucess is returned. Follow up by polling the `/logs/retrieve/results` API.
```json
{
"success": true
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The component name or id was not found
- Missing `View Logs` permission
- The start and end bounds are invalid for the selected search direction
- The async job could not be started
# `/logs/retrieve/results`
Return the current results for an asynchronous log search job.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `job` | string | Yes | - | Asynchronous job id returned by the retrieval flow. |
## Permissions
Required permissions:
* View Logs
## Example
```lua
local R = iguana.call{
component.runAsUser{user="admin"}
api="/logs/retrieve/results",
data={
job="job-123"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": [
{
"type": "error",
"time": "1777461600000",
"id": "12",
"size": "84",
"comp": "Orders",
"rel_comp": "",
"rel_time": "0",
"rel_id": "0",
"sid": "12",
"qid": "5",
"tags": ["#error"],
"match": true,
"content": "..."
}
],
"done": false,
"max_reached": false,
"end_of_logs": false,
"next_file": "1777461660000"
}
```
Fields:
- `data` is the array of results accumulated so far.
- `done` is `true` when the async job has finished.
- `max_reached` is `true` when the configured limit was reached.
- `end_of_logs` is `true` when the search reached the end of available logs.
- `next_file` is the timestamp of the next log file to process.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The job id was not found
- Missing `View Logs` permission
# `/user/add`
Create a local user account.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `username` | string | Yes | - | Username for the new account. Usernames cannot contain whitespace, be empty, or exceed 40 characters. |
| `password` | string | Yes | - | Password for the new account. |
| `roles` | array of strings | Yes | - | Roles assigned to the new account. Role names are stored as strings, such as `#operations`. |
Passwords must be at least 8 characters and contain an uppercase letter, a lowercase letter, and a numerical digit.
## Permissions
Required permissions:
* Edit Users
## Example
```lua
local R = iguana.call{
component.runAsUser{user="admin"}
api="/user/add",
data={
username="analyst",
password="TempPass1",
roles={"#operations", "#support"}
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- Missing `Edit Users` permission
- The `roles` field is missing or not formatted as an array
- The username contains whitespace, is empty, is too long, or already exists
- The password does not meet the password requirements
- The user configuration could not be saved
# `/user/delete`
Delete a local user account.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `username` | string | Yes | - | Username of the account to delete. |
## Permissions
Required permissions:
* Edit Users
## Example
```lua
local R = iguana.call{
component.runAsUser{user="admin"}
api="/user/delete",
data={
username="analyst"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- Missing `Edit Users` permission
- The user does not exist
- The request attempts to delete the currently signed-in user
- The user is an external user account
- The user directory could not be removed
# `/user/list`
List local user accounts.
## Parameters
This endpoint does not require any request parameters.
## Example
```lua
component.runAsUser{user="admin"}
local R = iguana.call{api="/user/list", data={}, live=false}
```
## Response
### Success
```json
{
"success": true,
"data": {
"admin": {
"username": "admin",
"display_name": "",
"provider": "",
"external": false,
"roles": ["#admin"]
},
"analyst": {
"username": "analyst",
"display_name": "",
"provider": "",
"external": false,
"roles": ["#operations", "#support"]
}
}
}
```
The response data is a map keyed by username. External users are not included.
User fields:
- `username` is the account username.
- `display_name` is the user's display name, when available.
- `provider` is the external identity provider, when available.
- `external` reports whether the user is managed externally.
- `roles` is the list of roles assigned to the user.
# `/user/set/password`
Set the password for a local user account.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `username` | string | Yes | - | Username of the account to update. |
| `current_password` | string | Yes | - | Current password for the account. Users with `Edit Users` permission must still provide this field, but it is not authenticated. |
| `password` | string | Yes | - | New password for the account. |
Passwords must be at least 8 characters and contain an uppercase letter, a lowercase letter, and a numerical digit.
## Permissions
Required permissions:
* Edit Users, when changing another user's password
Users may change their own password without `Edit Users` permission if `current_password` is correct.
## Example
```lua
local R = iguana.call{
component.runAsUser{user="admin"} -- or your user
api="/user/set/password",
data={
username="analyst",
current_password="TempPass1",
password="NewPass2"
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The user does not exist
- The user is an external user account
- Missing `Edit Users` permission when changing another user's password
- The current password is incorrect
- The new password does not meet the password requirements
- The user configuration could not be saved
# `/user/set/roles`
Set the roles for a local user account.
## Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `username` | string | Yes | - | Username of the account to update. |
| `roles` | array of strings | Yes | - | Complete list of roles to assign to the user. Role names are stored as strings, such as `#operations`. |
## Permissions
Required permissions:
* Edit Users
## Example
```lua
local R = iguana.call{
component.runAsUser{user="admin"}
api="/user/set/roles",
data={
username="analyst",
roles={"#operations", "#support"}
},
live=false
}
```
## Response
### Success
```json
{
"success": true,
"data": {}
}
```
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- Missing `Edit Users` permission
- The user does not exist
- The user is an external user account
- The `roles` field is missing or not formatted as an array
- The user configuration could not be saved
# `/user/whoami`
Return information about the current authenticated user.
## Parameters
This endpoint does not require any request parameters.
## Example
```lua
local R = iguana.call{api="/user/whoami", data={}, live=false}
```
## Response
### Success
```json
{
"success": true,
"data": {
"username": "admin",
"display_name": "",
"provider": "",
"external": false,
"roles": ["#admin"]
}
}
```
User fields:
- `username` is the account username.
- `display_name` is the user's display name, when available.
- `provider` is the external identity provider, when available.
- `external` reports whether the user is managed externally.
- `roles` is the list of roles assigned to the user.
### Error
```json
{
"success": false,
"error": "The error message outlines what went wrong."
}
```
Common errors:
- The current session user is not present in the user map