Skip to content
aerandil.com
GitHub

Withdraw a house's Watchtower contribution on its behalf

POST
/v1/watchtower/contributions/{contribution_id}/withdraw
curl --request POST \
  --url https://api.aerandil.com/v1/watchtower/contributions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/withdraw \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "reason": "example" }'

The platform’s review of a contest decides a contribution behind it should not stand: it is taken back out of the network on the contributing house’s behalf — the house’s own withdraw_fraud_signal, run in its tenant by the card rail, recorded withdrawn_by = platform with the reason prefixed platform review (<operator>). The next answer for the card no longer counts it; answers already given stand as given. The house sees the withdrawal on its own ledger and event log (fraud_network.contribution_withdrawn). 404 for an id that is no live contribution anywhere, 409 already_withdrawn for one already out. The platform operator’s (tenant_admin:write), cleared to read internal.restricted.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
contribution_id
required
string format: uuid

The fraud_network_contribution, in any tenant.

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters

Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
reason
required

Why the platform takes it back — what the review found.

string
>= 1 characters
Examplegenerated
{
  "reason": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

Withdrawn; the contribution as it now reads.

Media typeapplication/json
object
contribution_id
required
string format: uuid
property_id
string | null format: uuid
status
required
string
Allowed values: withdrawn
tenant_id
required
string format: uuid
withdrawal_reason
string | null
withdrawn_at
string | null format: date-time
withdrawn_by
required
string
Allowed values: platform
Example
{
  "status": "withdrawn",
  "withdrawn_by": "platform"
}

Headers

Section titled “Headers”
Cache-Control
string

Always no-store. Object and link state is live data and is never cacheable.

403

Section titled “403”

The bearer authenticated but does not hold the scope this operation requires.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object
error
required
object
code
required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string
instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string
message
required

Human-readable explanation of the failure.

string
parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Examplegenerated
{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}

404

Section titled “404”

No such object in the caller’s tenant — which is also the answer when it exists in another tenant, by design.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object
error
required
object
code
required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string
instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string
message
required

Human-readable explanation of the failure.

string
parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Examplegenerated
{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}

409

Section titled “409”

already_withdrawn — the contribution is already out of the network.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object
error
required
object
code
required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string
instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string
message
required

Human-readable explanation of the failure.

string
parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Examplegenerated
{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}

422

Section titled “422”

The request parsed but a validator refused it. The envelope’s code names which rule.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object
error
required
object
code
required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string
instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string
message
required

Human-readable explanation of the failure.

string
parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Examplegenerated
{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}