# com.atiproto.actions

> Published by [atiproto.com](https://lexicon.garden/identity/did:plc:4x5dcv6u4wlkjcssto7f22nu)

✓ This is the authoritative definition for this NSID.

## Description

Workflow envelope shared between atiproto XRPC endpoints and the agent interpreter. The server emits an outboundWorkflow when it needs the agent to execute repo writes against the user's PDS; the agent runs the actions and calls back with an inboundWorkflow.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:4x5dcv6u4wlkjcssto7f22nu/com.atiproto.actions)
- [Documentation](https://lexicon.garden/lexicon/did:plc:4x5dcv6u4wlkjcssto7f22nu/com.atiproto.actions/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:4x5dcv6u4wlkjcssto7f22nu/com.atiproto.actions/examples)

## Definitions

### `com.atiproto.actions#error`

**Type**: `object`

Populated by the agent when an action fails. The server's error branch uses this to construct compensating actions and a final raise.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `code` | `string` | No |  |
| `name` | `string` | No |  |
| `action` | `string` | Yes | The verb of the action that failed (create/update/delete). |
| `message` | `string` | Yes |  |

### `com.atiproto.actions#raise`

**Type**: `object`

Terminal action: the agent throws a WorkflowRaisedError carrying message and code. Subsequent actions in the same batch are not executed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `code` | `string` | No |  |
| `message` | `string` | Yes |  |

### `com.atiproto.actions#create`

**Type**: `object`

Instructs the agent to call com.atproto.repo.createRecord on the user's PDS.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes | Server-assigned name for this action; echoed back on the corresponding response so the server can correlate. |
| `repo` | `string` (did) | Yes | DID of the repo to write to. The PDS auth check is the source of truth for whether the write is allowed. |
| `rkey` | `string` | No | Optional. When omitted (the default), the PDS generates the rkey and returns the resulting URI on the response. Server-assigned rkeys are reserved for fixed-rkey records like com.atiproto.profile/self. |
| `record` | `unknown` | Yes |  |
| `collection` | `string` (nsid) | Yes |  |

### `com.atiproto.actions#delete`

**Type**: `object`

Instructs the agent to call com.atproto.repo.deleteRecord on the user's PDS.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes |  |
| `repo` | `string` (did) | Yes |  |
| `rkey` | `string` | Yes |  |
| `collection` | `string` (nsid) | Yes |  |
| `swapCommit` | `string` (cid) | No |  |

### `com.atiproto.actions#update`

**Type**: `object`

Instructs the agent to call com.atproto.repo.putRecord on the user's PDS.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes |  |
| `repo` | `string` (did) | Yes |  |
| `rkey` | `string` | Yes |  |
| `record` | `unknown` | Yes |  |
| `collection` | `string` (nsid) | Yes |  |
| `swapCommit` | `string` (cid) | No |  |

### `com.atiproto.actions#response`

**Type**: `object`

Result of executing one action. Carries the verb (so the server can branch without inspecting result shape) plus the action name and the resulting record reference.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes |  |
| `action` | `string` | Yes |  |
| `result` | `ref` → `#recordResult` | Yes |  |

### `com.atiproto.actions#recordResult`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `cid` | `string` (cid) | No | Present on create/update responses; absent on delete (the record is gone). |
| `uri` | `string` (at-uri) | Yes |  |

### `com.atiproto.actions#inboundWorkflow`

**Type**: `object`

Agent → server callback envelope. Echoes the server's intent verbatim, except when the agent overrides to "error" after an action failure.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error` | `ref` → `#error` | No |  |
| `intent` | `string` | Yes |  |
| `responses` | `array` | Yes |  |

### `com.atiproto.actions#outboundWorkflow`

**Type**: `object`

Server → agent envelope. Server-defined intent string acts as a phase marker; the agent treats it as opaque. Each item in `actions` is discriminated by `$type` against `#create` / `#update` / `#delete` / `#raise`.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `intent` | `string` | Yes |  |
| `actions` | `array` | Yes |  |

## Raw Schema

```json
{
  "id": "com.atiproto.actions",
  "defs": {
    "error": {
      "type": "object",
      "required": [
        "action",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "maxLength": 64
        },
        "name": {
          "type": "string",
          "maxLength": 64
        },
        "action": {
          "type": "string",
          "maxLength": 32,
          "description": "The verb of the action that failed (create/update/delete)."
        },
        "message": {
          "type": "string",
          "maxLength": 1024
        }
      },
      "description": "Populated by the agent when an action fails. The server's error branch uses this to construct compensating actions and a final raise."
    },
    "raise": {
      "type": "object",
      "required": [
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "maxLength": 64
        },
        "message": {
          "type": "string",
          "maxLength": 1024
        }
      },
      "description": "Terminal action: the agent throws a WorkflowRaisedError carrying message and code. Subsequent actions in the same batch are not executed."
    },
    "create": {
      "type": "object",
      "required": [
        "repo",
        "name",
        "collection",
        "record"
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 64,
          "description": "Server-assigned name for this action; echoed back on the corresponding response so the server can correlate."
        },
        "repo": {
          "type": "string",
          "format": "did",
          "description": "DID of the repo to write to. The PDS auth check is the source of truth for whether the write is allowed."
        },
        "rkey": {
          "type": "string",
          "maxLength": 128,
          "description": "Optional. When omitted (the default), the PDS generates the rkey and returns the resulting URI on the response. Server-assigned rkeys are reserved for fixed-rkey records like com.atiproto.profile/self."
        },
        "record": {
          "type": "unknown"
        },
        "collection": {
          "type": "string",
          "format": "nsid"
        }
      },
      "description": "Instructs the agent to call com.atproto.repo.createRecord on the user's PDS."
    },
    "delete": {
      "type": "object",
      "required": [
        "repo",
        "name",
        "collection",
        "rkey"
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 64
        },
        "repo": {
          "type": "string",
          "format": "did"
        },
        "rkey": {
          "type": "string",
          "maxLength": 128
        },
        "collection": {
          "type": "string",
          "format": "nsid"
        },
        "swapCommit": {
          "type": "string",
          "format": "cid"
        }
      },
      "description": "Instructs the agent to call com.atproto.repo.deleteRecord on the user's PDS."
    },
    "update": {
      "type": "object",
      "required": [
        "repo",
        "name",
        "collection",
        "rkey",
        "record"
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 64
        },
        "repo": {
          "type": "string",
          "format": "did"
        },
        "rkey": {
          "type": "string",
          "maxLength": 128
        },
        "record": {
          "type": "unknown"
        },
        "collection": {
          "type": "string",
          "format": "nsid"
        },
        "swapCommit": {
          "type": "string",
          "format": "cid"
        }
      },
      "description": "Instructs the agent to call com.atproto.repo.putRecord on the user's PDS."
    },
    "response": {
      "type": "object",
      "required": [
        "action",
        "name",
        "result"
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 64
        },
        "action": {
          "type": "string",
          "maxLength": 32,
          "knownValues": [
            "create",
            "update",
            "delete"
          ]
        },
        "result": {
          "ref": "#recordResult",
          "type": "ref"
        }
      },
      "description": "Result of executing one action. Carries the verb (so the server can branch without inspecting result shape) plus the action name and the resulting record reference."
    },
    "recordResult": {
      "type": "object",
      "required": [
        "uri"
      ],
      "properties": {
        "cid": {
          "type": "string",
          "format": "cid",
          "description": "Present on create/update responses; absent on delete (the record is gone)."
        },
        "uri": {
          "type": "string",
          "format": "at-uri"
        }
      }
    },
    "inboundWorkflow": {
      "type": "object",
      "required": [
        "intent",
        "responses"
      ],
      "properties": {
        "error": {
          "ref": "#error",
          "type": "ref"
        },
        "intent": {
          "type": "string",
          "maxLength": 64
        },
        "responses": {
          "type": "array",
          "items": {
            "ref": "#response",
            "type": "ref"
          }
        }
      },
      "description": "Agent → server callback envelope. Echoes the server's intent verbatim, except when the agent overrides to \"error\" after an action failure."
    },
    "outboundWorkflow": {
      "type": "object",
      "required": [
        "intent",
        "actions"
      ],
      "properties": {
        "intent": {
          "type": "string",
          "maxLength": 64
        },
        "actions": {
          "type": "array",
          "items": {
            "refs": [
              "#create",
              "#update",
              "#delete",
              "#raise"
            ],
            "type": "union"
          }
        }
      },
      "description": "Server → agent envelope. Server-defined intent string acts as a phase marker; the agent treats it as opaque. Each item in `actions` is discriminated by `$type` against `#create` / `#update` / `#delete` / `#raise`."
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1,
  "description": "Workflow envelope shared between atiproto XRPC endpoints and the agent interpreter. The server emits an outboundWorkflow when it needs the agent to execute repo writes against the user's PDS; the agent runs the actions and calls back with an inboundWorkflow."
}
```