RIPE Atlas Documentation

PATCH /ambassadors/probes/{id}/ ​

Retrieve or update a probe that the user is an ambassador of. Retrieval takes ambassadors.get_ambassador_probe_info; updating takes ambassadors.change_ambassador_probe. The two grants are independent, so a read-only key stays read-only. state is restricted on writes, for session and key alike — see AmbassadorProbeWriteSerializer. Every other field is as writable by a key as it is from the UI, including email, which triggers the host's initial email. PATCH is the verb to use: comment and state are both required, so a PUT missing either is a 400.

PATCH /ambassadors/probes/{id}/ — id ​

The unique ambassadorship ID. This identifies the record linking an ambassador to a probe they handed out -- it is not the probe ID.

PATCH /ambassadors/probes/{id}/ — include ​

Include additional fields named in comma-separated values in response as nested JSON objects.

PATCH /api/v2/ambassadors/probes/{id}/​

Retrieve or update a probe that the user is an ambassador of.

Retrieval takes ambassadors.get_ambassador_probe_info; updating takes ambassadors.change_ambassador_probe. The two grants are independent, so a read-only key stays read-only.

state is restricted on writes, for session and key alike — see AmbassadorProbeWriteSerializer. Every other field is as writable by a key as it is from the UI, including email, which triggers the host's initial email. PATCH is the verb to use: comment and state are both required, so a PUT missing either is a 400.

Try it out

Playground​

Authorization
Variables
Key
Value
Body
Authorizations

Authorizations​

api-key
Type
API Key (header: Authorization)
or
session
Type
API Key (cookie: atlasess)
Parameters

Path Parameters

id*

The unique ambassadorship ID. This identifies the record linking an ambassador to a probe they handed out -- it is not the probe ID.

Type
integer
Required

Query Parameters

include

Include additional fields named in comma-separated values in response as nested JSON objects.

Type
string
Valid values
"probe"
Request Body

Request Body​

object

AmbassadorProbeListSerializer with state restricted to what an
ambassador is actually entitled to set.

Used for every write to the detail view — session and API key alike. The
model field allows all eleven states, and the rest are not the
ambassador's to set:

  • RESET (0) is described in signals.py as dev-only, and nothing enforced
    that. It wipes the host email/name and every date, re-saves the row as
    WITH_AMBASSADOR and detaches probe.prb_user. This is the one the
    restriction is really for.
  • APPLIED, HOSTED, ONLINE and WITH_AMBASSADOR are driven by the
    sync task and the application flow.

Three things are allowed, and the last two are why this is a
validate_state rather than a narrower choice list:

  1. The five AMBASSADOR_STATES. That tuple has been on the model since it
    was written with no reader anywhere; it is the intent, just never
    enforced.
  2. HANDED_OUT — handing a probe to someone is the ambassador action, and
    AMBASSADOR_STATES simply omits it. The hand-out dialog posts it
    directly.
  3. Re-sending the state the row is already in. The edit dialog seeds its
    form from the current row and posts state back on every save, so
    editing a comment on a HOSTED probe re-submits HOSTED. That is a no-op,
    and refusing it would break commenting on any probe outside the list
    above.

Reads keep the model's full choice list, so a row parked in any state
still serialises normally — only setting one is restricted.

Max Length64
Maximum2147483647
Minimum-2147483648
Max Length100
Max Length240
Format"email"
Max Length128
Max Length240
Format"date"
Format"date"
Format"date"
Format"date"
Format"date"
Format"date"
Format"date-time"
  • 0 - Reset
  • 1 - Given to ambassador
  • 2 - Handed out
  • 3 - Applied
  • 5 - Hosted
  • 4 - Online, not hosted
  • 6 - Written off
  • 10 - Returned
  • 7 - Refurbished
  • 8 - Lost in transit
  • 9 - Broken
Valid values012354610789
Responses

Responses​

application/json
object

AmbassadorProbeListSerializer with state restricted to what an
ambassador is actually entitled to set.

Used for every write to the detail view — session and API key alike. The
model field allows all eleven states, and the rest are not the
ambassador's to set:

  • RESET (0) is described in signals.py as dev-only, and nothing enforced
    that. It wipes the host email/name and every date, re-saves the row as
    WITH_AMBASSADOR and detaches probe.prb_user. This is the one the
    restriction is really for.
  • APPLIED, HOSTED, ONLINE and WITH_AMBASSADOR are driven by the
    sync task and the application flow.

Three things are allowed, and the last two are why this is a
validate_state rather than a narrower choice list:

  1. The five AMBASSADOR_STATES. That tuple has been on the model since it
    was written with no reader anywhere; it is the intent, just never
    enforced.
  2. HANDED_OUT — handing a probe to someone is the ambassador action, and
    AMBASSADOR_STATES simply omits it. The hand-out dialog posts it
    directly.
  3. Re-sending the state the row is already in. The edit dialog seeds its
    form from the current row and posts state back on every save, so
    editing a comment on a HOSTED probe re-submits HOSTED. That is a no-op,
    and refusing it would break commenting on any probe outside the list
    above.

Reads keep the model's full choice list, so a row parked in any state
still serialises normally — only setting one is restricted.

Max Length64

The unique identifier of this probe.

Maximum2147483647
Minimum-2147483648
Max Length100
Max Length240
Format"email"
Max Length128
Max Length240
Format"date"
Format"date"
Format"date"
Format"date"
Format"date"
Format"date"
Format"date-time"
  • 0 - Reset
  • 1 - Given to ambassador
  • 2 - Handed out
  • 3 - Applied
  • 5 - Hosted
  • 4 - Online, not hosted
  • 6 - Written off
  • 10 - Returned
  • 7 - Refurbished
  • 8 - Lost in transit
  • 9 - Broken
Valid values012354610789
Samples