Read one decision

GET

/v1/decisions/{decision_id}

curl --request GET \
  --url https://api.hydrate.sh/v1/decisions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

• Production

One decision by id.

Requires the decisions:read scope. A decision you may not read — because it belongs to another project, or is still mid-conversation — returns the same 404 as one that does not exist.

The URL is flat (no project component) because a decision id is globally unique. Authorization is still per project: the row is loaded, then its project is resolved through the membership gate, then the state filter — every one of those failures producing the SAME 404 a nonexistent id gets, so this route is not an oracle for “that decision exists but you may not see it”.

Authorizations

• Bearer

Parameters

Path Parameters

decision_id

required

Decision Id

string format: uuid

Responses

200

Successful Response

Media typeapplication/json

DecisionResponse

object

decision

required

DecisionOut

A decision as the /v1 surface serves it.

A focused read view: the decision’s identity, anchor, state, and the fields a caller needs to reason about what has been decided. The shape is intentionally minimal and stable, so it won’t churn as the product grows.

object

anchor_ref

required

AnchorRef

Where a decision is anchored. id is a free-text reference whose meaning depends on type (a node/boundary UUID, an error payload key, or absent for a project-level decision).

type is an OPEN set, published as a plain string, for exactly the reason Finding.code is — see that model. The anchor vocabulary is server-owned and grows additively as new things become anchorable, so a consumer must tolerate a type it does not recognize.

object

id

required

Any of:

string

string

null

null

type

required

Type

What the decision is anchored to. Known values: boundary, node, error_payload, project. This set is open and grows additively — treat an unrecognized type as an opaque string and render it; do not fail on it.

string

annotations

required

Any of:

string

string

null

null

applied

required

Any of:

boolean

boolean

null

null

capture_text

required

Any of:

string

string

null

null

captured_at

required

Captured At

string

check

required

Any of:

string

string

null

null

id

required

Id

string format: uuid

parent_decision_id

required

Any of:

string

string format: uuid

null

null

project_id

required

Project Id

string format: uuid

resulting_node_ids

required

Any of:

Array<string>

Array<string>

null

null

retirement_reason

required

Any of:

string

string

null

null

state

required

State

string

superseded_by

required

Any of:

string

string format: uuid

null

null

project_id

required

Project Id

string format: uuid

version

required

Version

string

Example

{
  "decision": {
    "anchor_ref": {
      "type": "node"
    }
  }
}

401

No credentials, malformed credentials, or revoked credentials. The envelope is leak-parity (same shape across all 401 paths) so an attacker cannot distinguish revoked vs. unknown via the body.

Media typeapplication/json

object

detail

required

string

Example

{
  "detail": "unauthenticated"
}

403

Credentials are valid but lack the scope required for this route, or the principal lacks membership in the target project.

Media typeapplication/json

object

detail

object

code

string

message

string

Example^generated

{
  "detail": {
    "code": "example",
    "message": "example"
  }
}

404

Resource not found OR not accessible to this principal. Leak parity: the response is identical in both cases so an attacker cannot enumerate resources via 404-vs-403 timing.

Media typeapplication/json

object

detail

object

code

string

message

string

Example

{
  "detail": {
    "code": "not_found"
  }
}

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

ctx

Context

object

input

Input

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Example^generated

{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}

429

Per-bucket rate limit exceeded. The response carries Retry-After and the standard X-RateLimit-* headers (Limit / Remaining / Reset).

Media typeapplication/json

object

detail

string

Example

{
  "detail": "rate_limited"
}

Headers

Retry-After

integer

X-RateLimit-Limit

integer

X-RateLimit-Remaining

integer

X-RateLimit-Reset

integer