> For the complete documentation index, see [llms.txt](https://docs.sygnal.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sygnal.network/specification/apis/policy-update.md).

# policy/update

Distribute a signed coordination policy from governance to an edge; the edge confirms adoption.

|               |                                                                                                            |
| ------------- | ---------------------------------------------------------------------------------------------------------- |
| **Endpoint**  | `POST /sygnal/policy/update`                                                                               |
| **Callback**  | `POST /sygnal/policy/on_update`                                                                            |
| **Direction** | Governance (via the Policy Manager) → edge. It is the only verb that sends configuration down to the edge. |
| **Sender**    | A participant with the `GOVERNANCE` role                                                                   |
| **Payload**   | `sygnal:CoordinationPolicy`                                                                                |
| **Responses** | `200` (callback follows), `202`, `400`, `401`, `403`, `500`                                                |

## When to use it

Push a new or revised [coordination policy](/concepts/policies.md) to the edges in its scope. Edges that were offline, or that are starting up, fetch their applicable policies with [`policy/get`](/specification/apis/reads.md) instead.

A network can start without policies; see [Starting without encoded policies](/concepts/policies.md#starting-without-encoded-policies).

## Rules

* The edge **MUST** verify that the sender holds the `GOVERNANCE` role before applying the policy (`401 AUT_UNAUTHORIZED_ACTION` otherwise). A forged policy could widen what leaves the edge.
* The edge ignores sections whose `@type` it doesn't recognise, **unless** a section is `critical: true`. Then it rejects the whole policy.
* A `PrecedenceSection` is valid only in a network-wide policy (one with no `scope`).
* When several policies apply, the edge computes its effective policy using the network's declared precedence, and **always** merges `dataMinimization` to the most restrictive result.
* `InstrumentationSection.level: PER_TRANSACTION` is valid only when the network's `PrecedenceSection` declares `environment: NON_PRODUCTION`, and it requires `until`.

## Callback: `policy/on_update`

The edge returns the policy with `edgeStatus` set to:

* `APPLIED`, or
* `REJECTED`, with an `edgeStatusReason`, for example naming an unrecognised critical section type.

## Example

See the example in [Coordination policies](/concepts/policies.md#example), and the full examples (a scoped policy and a network-wide precedence policy) in the [OpenAPI reference](/specification/api-reference.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sygnal.network/specification/apis/policy-update.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.