com.atiproto.actions

{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "create": {
      "description": "Instructs the agent to call com.atproto.repo.createRecord on the user's PDS.",
      "properties": {
        "collection": {
          "format": "nsid",
          "type": "string"
        },
        "name": {
          "description": "Server-assigned name for this action; echoed back on the corresponding response so the server can correlate.",
          "maxLength": 64,
          "type": "string"
        },
        "record": {
          "type": "unknown"
        },
        "repo": {
          "description": "DID of the repo to write to. The PDS auth check is the source of truth for whether the write is allowed.",
          "format": "did",
          "type": "string"
        },
        "rkey": {
          "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.",
          "maxLength": 128,
          "type": "string"
        }
      },
      "required": [
        "repo",
        "name",
        "collection",
        "record"
      ],
      "type": "object"
    },
    "delete": {
      "description": "Instructs the agent to call com.atproto.repo.deleteRecord on the user's PDS.",
      "properties": {
        "collection": {
          "format": "nsid",
          "type": "string"
        },
        "name": {
          "maxLength": 64,
          "type": "string"
        },
        "repo": {
          "format": "did",
          "type": "string"
        },
        "rkey": {
          "maxLength": 128,
          "type": "string"
        },
        "swapCommit": {
          "format": "cid",
          "type": "string"
        }
      },
      "required": [
        "repo",
        "name",
        "collection",
        "rkey"
      ],
      "type": "object"
    },
    "error": {
      "description": "Populated by the agent when an action fails. The server's error branch uses this to construct compensating actions and a final raise.",
      "properties": {
        "action": {
          "description": "The verb of the action that failed (create/update/delete).",
          "maxLength": 32,
          "type": "string"
        },
        "code": {
          "maxLength": 64,
          "type": "string"
        },
        "message": {
          "maxLength": 1024,
          "type": "string"
        },
        "name": {
          "maxLength": 64,
          "type": "string"
        }
      },
      "required": [
        "action",
        "message"
      ],
      "type": "object"
    },
    "inboundWorkflow": {
      "description": "Agent → server callback envelope. Echoes the server's intent verbatim, except when the agent overrides to \"error\" after an action failure.",
      "properties": {
        "error": {
          "ref": "#error",
          "type": "ref"
        },
        "intent": {
          "maxLength": 64,
          "type": "string"
        },
        "responses": {
          "items": {
            "ref": "#response",
            "type": "ref"
          },
          "type": "array"
        }
      },
      "required": [
        "intent",
        "responses"
      ],
      "type": "object"
    },
    "outboundWorkflow": {
      "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`.",
      "properties": {
        "actions": {
          "items": {
            "refs": [
              "#create",
              "#update",
              "#delete",
              "#raise"
            ],
            "type": "union"
          },
          "type": "array"
        },
        "intent": {
          "maxLength": 64,
          "type": "string"
        }
      },
      "required": [
        "intent",
        "actions"
      ],
      "type": "object"
    },
    "raise": {
      "description": "Terminal action: the agent throws a WorkflowRaisedError carrying message and code. Subsequent actions in the same batch are not executed.",
      "properties": {
        "code": {
          "maxLength": 64,
          "type": "string"
        },
        "message": {
          "maxLength": 1024,
          "type": "string"
        }
      },
      "required": [
        "message"
      ],
      "type": "object"
    },
    "recordResult": {
      "properties": {
        "cid": {
          "description": "Present on create/update responses; absent on delete (the record is gone).",
          "format": "cid",
          "type": "string"
        },
        "uri": {
          "format": "at-uri",
          "type": "string"
        }
      },
      "required": [
        "uri"
      ],
      "type": "object"
    },
    "response": {
      "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.",
      "properties": {
        "action": {
          "knownValues": [
            "create",
            "update",
            "delete"
          ],
          "maxLength": 32,
          "type": "string"
        },
        "name": {
          "maxLength": 64,
          "type": "string"
        },
        "result": {
          "ref": "#recordResult",
          "type": "ref"
        }
      },
      "required": [
        "action",
        "name",
        "result"
      ],
      "type": "object"
    },
    "update": {
      "description": "Instructs the agent to call com.atproto.repo.putRecord on the user's PDS.",
      "properties": {
        "collection": {
          "format": "nsid",
          "type": "string"
        },
        "name": {
          "maxLength": 64,
          "type": "string"
        },
        "record": {
          "type": "unknown"
        },
        "repo": {
          "format": "did",
          "type": "string"
        },
        "rkey": {
          "maxLength": 128,
          "type": "string"
        },
        "swapCommit": {
          "format": "cid",
          "type": "string"
        }
      },
      "required": [
        "repo",
        "name",
        "collection",
        "rkey",
        "record"
      ],
      "type": "object"
    }
  },
  "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.",
  "id": "com.atiproto.actions",
  "lexicon": 1
}