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

> ## Agent Instructions
> Melso product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# Idempotency

> Retry supported writes without creating duplicate work.

<Info>Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).</Info>

There is no universal `Idempotency-Key` contract across the REST API. Use the request field supported by the operation you are calling.

## Create a Task

`POST /api/tasks` accepts a caller-generated UUID in `client_request_id`. The key is scoped to the actor and company. Reuse it with the same payload after a network timeout. An identical replay returns **`201`**, the same status as the original create, with the existing Task's current state and original `run_id`. It creates no new Task or Run. Do not count the replay's `201` as a new resource.

Changing the payload while reusing the key returns `409` with `code: "client_request_conflict"`.

```json theme={null}
{
  "client_request_id": "11111111-1111-4111-8111-111111111111",
  "title": "Review my draft",
  "input": "Check the attached draft for missing sections.",
  "execution": { "harness": "codex" }
}
```

Generate your own UUID for new work; the example UUID is illustrative. Persist the UUID and payload before sending the request.

## Send a follow-up

`POST /api/tasks/{id}/input` also accepts `client_request_id`. It is scoped to the actor and Task. Identical retries return the original input receipt, including its message and Run identifiers; conflicting reuse is rejected.

## Edit company definitions

Definition authoring uses `idempotency_key` in its request body. Keep that key stable when retrying the same Area, resource, Automation or trigger edit. Follow any returned saved-but-not-active conflict before submitting another change.

For endpoints without an explicit retry contract, read the resource after an uncertain result. Do not assume a timed-out write failed.


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