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

# Action safety

> How Equated previews, validates, and records AI-driven changes.

Equated's API is built on actions. An action is a request to change the books. Categorize a transaction. Link a receipt. Confirm a bill. Create a journal entry.

Key idea: Your AI doesn't directly edit the books. It asks Equated to perform an action. Equated validates it.

## The safety loop

<Steps>
  <Step title="Preview">
    Equated shows what would change before anything commits.
  </Step>

  <Step title="Commit">
    When you're ready, Equated records the action request.
  </Step>

  <Step title="Execute">
    Equated applies the request and records the result.
  </Step>
</Steps>

## Why this works

From your perspective, actions answer one question: what changed and can you trust it?

For your AI, actions provide a clear contract:

* Inputs are typed and validated.
* Effects can be previewed first.
* The server validates all writes.
* Changes can be audited and traced.
* Who or what made the change is recorded.

## Example

```bash theme={null}
curl https://app.equated.co/api/actions/preview \
  -H "Authorization: Bearer int_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "edit_postings",
    "journalEntryId": 123,
    "postings": [
      { "accountId": 10, "amount": "42.00", "currency": "USD" },
      { "accountId": 20, "amount": "-42.00", "currency": "USD" }
    ],
    "commit": true
  }'
```

## What actions exist

| Kind                                     | What it does                                                                                                                                                                                                         |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `attach_evidence`                        | Link a receipt, bill, or invoice to a transaction.                                                                                                                                                                   |
| `enrich`                                 | Link a document and set the transaction's categorized postings in one step.                                                                                                                                          |
| `detach_receipt`                         | Remove a document from a transaction.                                                                                                                                                                                |
| `edit_postings`                          | Re-label, split, or merge a journal entry by replacing its posting set.                                                                                                                                              |
| `post_transaction`, `unpost_transaction` | Confirm a transaction, or unconfirm it for correction.                                                                                                                                                               |
| `confirm_document`, `unconfirm_document` | Move a bill, invoice, or reimbursement out of the inbox, or back into it.                                                                                                                                            |
| `convert_document_type`                  | Reclassify a document between bill, invoice, receipt, and reimbursement.                                                                                                                                             |
| `create_journal_entry`                   | Post an adjustment or reclass from balanced entries.                                                                                                                                                                 |
| `void_journal_entry`                     | Undo a manual journal entry. It leaves your balances; the row stays for audit.                                                                                                                                       |
| `delete_transaction`                     | Delete a transaction that isn't confirmed — voids its posted entries, removes its drafts, unlinks any bills it paid, and drops any transfer pairing it's part of. A confirmed transaction must be unconfirmed first. |

`GET /api/actions/catalog` returns this list live.

## Shortcuts for common work

The everyday verbs — confirming a transaction or a document, applying a bill payment or an invoice collection — have direct one-call endpoints and skip the preview step. They still record an action behind the scenes, so the audit trail is the same.

Several accept a batch of ids and answer per row, so one row failing never blocks the rest. You get back which ids succeeded and why each failure failed.