> ## Documentation Index
> Fetch the complete documentation index at: https://developers.arg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions

> One typed catalog of capabilities - generate media, call an integration, transform a file - callable by your code and by agents through the same endpoint.

An **Action** is a typed capability with a JSON Schema for its input and its output: generate an image, render HTML to PDF, create a GitHub issue, search a CRM, transform a file. Agents reach the catalog through a small set of meta-tools; your own code reaches the same catalog over HTTP, and both produce the same run records.

Actions span image, video, audio, 3D, document, file, web, data, and integration categories. New ones appear in the catalog without an API change on your side, which is the point of a registry rather than an endpoint per capability.

```bash theme={null}
export ARG_API_KEY="arg_live_your_key_here"
export ARG_API="https://api.arg.ai"
```

## Find an Action

```bash theme={null}
curl -sS "$ARG_API/api/actions?q=image&schema=1" -H "X-API-Key: $ARG_API_KEY"
```

| Query      | Effect                                             |
| ---------- | -------------------------------------------------- |
| `q`        | Free-text filter over id, name, and description.   |
| `category` | Filter by category, for example `image` or `file`. |
| `schema=1` | Include input and output schemas inline.           |

Ids read as `category_verb` - `image_generate`, `file_write`, `html_to_pdf`. If you guess `generate_image` and get a `404`, the error suggests the right id.

Fetch one Action's schemas on their own:

```bash theme={null}
curl -sS "$ARG_API/api/actions/image_generate/schema" -H "X-API-Key: $ARG_API_KEY"
```

## Run one

```bash theme={null}
curl -sS -X POST "$ARG_API/api/workspaces/$WS/actions/image_generate/run" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "A topographic map of an island, flat vector style",
      "output_path": "/assets/island.png"
    }
  }'
```

```json theme={null}
{ "runId": "…", "status": "succeeded", "output": { "path": "/assets/island.png" } }
```

Fast Actions return `output` in the response. Long-running ones return `queued` or `running` with a `runId` to poll:

```bash theme={null}
curl -sS "$ARG_API/api/workspaces/$WS/actions/runs/$RUN_ID" -H "X-API-Key: $ARG_API_KEY"
```

Run status is one of `queued`, `running`, `succeeded`, `failed`, or `canceled`. A run record also carries `progress` while it is in flight and `error` when it fails.

To follow a run without polling, read its status stream. Every `data:` frame is the same JSON the run endpoint returns, sent when it changes, and the stream ends with an `event: end` frame once the run is over:

```bash theme={null}
curl -sSN "$ARG_API/api/workspaces/$WS/actions/runs/$RUN_ID/events" -H "X-API-Key: $ARG_API_KEY"
```

If the connection drops, reconnect with `?cursor=<last id>` (the last `id:` line you received) to resume without replaying history. Imports, media generation jobs, site builds and workspace copies expose the same `/events` shape beside their status endpoints.

### Repeating a call safely

Pass `idempotencyKey` and a repeated call returns the original run instead of doing the work twice. Worth doing for anything that costs money or writes a file, since retries are the normal shape of a scheduled job.

```json theme={null}
{ "input": { "…": "…" }, "idempotencyKey": "monthly-cover-2026-08" }
```

### Actions that write require write access

An Action's declared permission decides what it needs: read-only Actions need workspace read, anything that writes needs workspace write. A credential without it gets `403` before the Action runs.

## Run several at once

A dashboard that renders from a dozen independent reads should not pay a dozen round trips. Send them as one batch of up to 50 calls:

```bash theme={null}
curl -sS -X POST "$ARG_API/api/workspaces/$WS/actions/run-batch" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "calls": [
      { "actionId": "file_read", "input": { "path": "/data/q1.csv" } },
      { "actionId": "file_read", "input": { "path": "/data/q2.csv" } },
      { "actionId": "get_stock_data", "input": { "symbol": "NET" } }
    ]
  }'
```

A batch is **not** a transaction. Every call reports its own outcome and the response is `200` even when some fail:

```json theme={null}
{
  "results": [
    { "ok": true, "actionId": "file_read", "run": { "runId": "…", "status": "succeeded", "output": {} } },
    { "ok": false, "actionId": "get_stock_data", "error": { "code": "…", "message": "…" } }
  ]
}
```

Results line up positionally with the calls you sent. An unknown `actionId` fails the whole request with a `404` rather than half-running the batch.

## Fields whose options depend on other fields

Some inputs cannot be enumerated up front - the folders in a connected Drive account, the models available for an image Action. Resolve those at call time:

```bash theme={null}
curl -sS "$ARG_API/api/workspaces/$WS/actions/image_generate/describe?field=model&q=fast" \
  -H "X-API-Key: $ARG_API_KEY"
```

## Reviewing what ran

```bash theme={null}
# Recent runs in a workspace
curl -sS "$ARG_API/api/workspaces/$WS/actions/runs?status=failed&limit=20" \
  -H "X-API-Key: $ARG_API_KEY"
```

Runs record which Action ran, its status, its output, and its cost, whoever started it - an agent turn, an automation, the product UI, or your own call. That makes the run list the single place to answer "what did this workspace actually do".

## How agents use the same catalog

Agents do not carry a tool per Action. They get four meta-tools - search, describe, run, and list runs - and pull a schema only when they need it. So an Action you can call over HTTP is one an agent in the same workspace can already use, with no registration step and no prompt changes.

To let an agent use an Action you have already scripted, just tell it what you want in plain language; it will find the id itself.

## Related

* [`@arg/actions` for React apps](/guides/apps/actions-sdk) - discover and run Actions from a live TSX or JSX preview
* [Agents overview](/guides/agents/overview) - where Actions sit among an agent's abilities
* [Integrations](/guides/integrations/overview) - connecting the accounts integration Actions call
* [Actions API reference](/api-reference/actions/list-actions) - every endpoint and parameter