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

# Post to a Case

> Send a case you own an action or a note as a person; the agent reads who sent it and sets the state

## Overview

A person works a case by sending it an event.

Give an `action`, a `note` or both: one of the goal's `person_actions`, or free text up to 4,000 characters.

An action also records the case's `last_event`: what, who, when, the inputs and the note. A note alone does not.

The event takes the same door as [Events](https://docs.oneshotagent.com/api-reference/compute/events.md) with one difference: it wakes an existing case only and never opens one; a key with no case is `404`.

Each accepted post is written to the organization audit log as `org.case_event_posted`.

## Authentication

A signed-in organization member. A member may post only to the cases they own, where the record's `owner` is their email ([My cases](https://docs.oneshotagent.com/api-reference/compute/cases-mine.md)); an admin may post to any case in the organization.

## Path Parameters

**goalId** `string` *required*

The goal the case belongs to

**key** `string` *required*

The case key

## Query Parameters

**key** `string`

For a key no path segment carries (`.` and `..` fold away in URL parsing): `/cases/-/events?key=..`, where the segment is a placeholder.

## Request Body

**action** `string`

One of the goal's `person_actions`

**note** `string`

Up to 4,000 characters

**inputs** `object`

With `action`: its inputs from the goal's case view, by key. A choice read from the case must be one the case offers. Numbers as numbers, times ISO 8601 with a zone. Kept as the case's `recorded`

## Response

**data.outcome** `string`

`already_open` when the case was running or waiting, `reopened` when it had finished and this post reopened it

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/org/goals/3f2b9c1e-8d4a-4f6b-9e2a-7c1d5b8a0f42/cases/invoice-2026-10-0007/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session token>" \
  -d '{ "action": "approve", "inputs": { "approved_usd": 1240 }, "note": "The total matches the purchase order." }'
```

```json 202 theme={null}
{
  "success": true,
  "data": {
    "goal_id": "3f2b9c1e-8d4a-4f6b-9e2a-7c1d5b8a0f42",
    "case_key": "invoice-2026-10-0007",
    "outcome": "already_open"
  }
}
```

## Errors

| Code | Status | When |
| - | - | - |
| `invalid_request` | 400 | Neither `action` nor `note`, an empty note, a note over 4,000 characters, or `inputs` without `action` |
| `invalid_action` | 400 | `action` is not one of the goal's `person_actions`; the answer lists them as `allowed` |
| `invalid_inputs` | 400 | An input the action does not declare, a missing required one, or a wrong value |
| `not_case_owner` | 403 | The caller does not own the case and is not an admin |
| `goal_not_found` | 404 | The goal is not in the caller's organization |
| `case_not_found` | 404 | No case has that key; none is opened |
| `action_not_offered` | 409 | State outside the action's `when_states` |
| `run_not_due` | 409 | A recurring goal between runs; `retry_at` says when |
| `goal_not_running` | 409 | The goal is not active, so it takes no events; `message` names its status |
| `not_on_the_agent_loop` | 409 | The goal is not on the agent loop, so it has no cases to send events to |
| `refused` | 409 | The case refused the wake: the owner cancelled it, it is held at its unit ceiling or as unreached until the owner approves more, or its scoped units are spent; `message` says which |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.