# Ames Scry Reference

Here are the scry endpoints of Ames. All of them take a `%x` `$care` and require the `$desk` in the path prefix be empty, so the general format is `.^([type] %ax /=//=/[some-path])`.

## /protocol/version <a href="#protocolversion" id="protocolversion"></a>

A scry with a `%x` `$care` and a `$path` of `/protocol/version` will return the current Ames protocol version as a `@`.

#### Example

```
> .^(@ %ax /=//=/protocol/version)
0
```

## /peers <a href="#peers" id="peers"></a>

A scry with a `%x` `$care` and a `$path` of `/peers` will return all ships that Ames is aware of. The type returned is a `(map ship ?(%alien %known))`, where `%known` means we have PKI data for them and `%alien` means we don't.

#### Example

```
> .^((map ship ?(%alien %known)) %ax /=//=/peers)
{[p=~wet q=%known] [p=~nes q=%known]}
```

## /peers/\[ship] <a href="#peersship" id="peersship"></a>

A scry with a `%x` `$care` and a `$path` of `/peers/[ship]` where `[ship]` is a ship name like `~dopzod` will return everything Ames knows about that ship, or crash if the ship is unknown to Ames. The type returned is a [`$ship-state`](/urbit-os/kernel/ames/data-types.md#ship-state).

#### Example

```
> .^(ship-state:ames %ax /=//=/peers/~nes)
[ %known
  [ symmetric-key=0wEF.5-Mp4.ehBxk.a-ktl.CAUHq.~XNVq.AfPFk.TwBbj.rc7MS
    life=1
    public-key=0w9R.IG6Km.CQfuL.lP9Da.l~kh1.lOHzV.xactk.1ybiB.hekW~.VC2d0.DDRsU.h6GHl.PKmRX.p3u2-.vO4Hg.QTOlp.A4AI0.uGPVy
    sponsor=~nes
  ]
  route=[~ [direct=%.y lane=[%.y p=~nes]]]
  qos=[%dead last-contact=~2021.8.9..16.11.36..fdbc]
    ossuary
  [ next-bone=4
    by-duct={[p=~[/gall/sys/way/~nes/hood /gall/use/hood/0w2.4d7EV/out/~nes/hood/helm/hi/~nes /dill //term/1] q=0]}
    by-bone={[p=0 q=~[/gall/sys/way/~nes/hood /gall/use/hood/0w2.4d7EV/out/~nes/hood/helm/hi/~nes /dill //term/1]]}
  ]
    snd
  { [ p=0
        q
      [ current=2
        next=3
        unsent-messages={}
        unsent-fragments=~
        queued-message-acks={}
          packet-pump-state
        [ next-wake=[~ ~2021.8.17..02.21.14..3d23]
          live={[[message-num=2 fragment-num=0] [last-sent=~2021.8.17..02.19.14..3d23 retries=2.255 skips=0] num-fragments=1 fragment=0w2.QJ1qS.JzaQn.w7rMp.IzuTJ.7M7aP.-1s~1]}
          metrics=[rto=~m2 rtt=~s1 rttvar=~s1 ssthresh=1 cwnd=1 num-live=1 counter=1]
        ]
      ]
    ]
  }
  rcv={}
  nax={}
  heeds={~[/gall/sys/lag /dill //term/1]}
]
```

## /peers/\[ship]/forward-lane <a href="#peersshipforward-lane" id="peersshipforward-lane"></a>

A scry with a `%x` `$care` and a `$path` of `/peers/[ship]/forward-lane` where `[ship]` is a ship name like `~dopzod` will return outbound routes to the given ship, or `~` if there are none. The type returned is a `(list lane:ames)`, see [`$lane`](/urbit-os/kernel/ames/data-types.md#lane) for type details.

#### Examples

```
> .^((list lane:ames) %ax /=//=/peers/~nes/forward-lane)
~[[%.y p=~nes]]
```

```
> .^((list lane:ames) %ax /=//=/peers/~nec/forward-lane)
~
```

## /bones/\[ship] <a href="#bonesship" id="bonesship"></a>

A scry with a `%x` `$care` and a `$path` of `/bones/[ship]` where `[ship]` is a ship name like `~dopzod` will return inbound and outbound [`$bone`](/urbit-os/kernel/ames/data-types.md#bone)s, which index message flows. If the ship in question is unknown to Ames, the scry will fail. The type returned is `[snd=(set bone) rcv=(set bone)]`.

#### Example

```
> .^([snd=(set bone) rcv=(set bone)] %ax /=//=/bones/~nes)
[snd={0} rcv={}]
```

## /snd-bones/\[ship]/\[bone] <a href="#snd-bonesshipbone" id="snd-bonesshipbone"></a>

A scry with a `%x` `$care` and a `$path` of `/snd-bones/[ship]/[bone]`, where `[ship]` is a ship name like `~dopzod` and `[bone]` is an outbound [`$bone`](/urbit-os/kernel/ames/data-types.md#bone), will return message flow details for that `$bone`. If the ship in question is unknown to Ames or the `$bone` does not exist, the scry will fail. The type returned is a [`$message-pump-state`](/urbit-os/kernel/ames/data-types.md#message-pump-state) wrapped in a `$vase`.

#### Example

```
> !<  message-pump-state:ames  .^(vase %ax /=//=/snd-bones/~nes/0)
[ current=2
  next=3
  unsent-messages={}
  unsent-fragments=~
  queued-message-acks={}
    packet-pump-state
  [ next-wake=[~ ~2021.8.17..02.27.14..aaff]
      live
    { [ [message-num=2 fragment-num=0]
        [last-sent=~2021.8.17..02.25.14..aaff retries=2.258 skips=0]
        num-fragments=1
        fragment=0w2.QJ1qS.JzaQn.w7rMp.IzuTJ.7M7aP.-1s~1
      ]
    }
    metrics=[rto=~m2 rtt=~s1 rttvar=~s1 ssthresh=1 cwnd=1 num-live=1 counter=1]
  ]
]
```

## /snubbed <a href="#snubbed" id="snubbed"></a>

A scry with a `%x` `$care` and a `$path` of `/snubbed` will return Ames' current ship whitelist/blacklist. The type is a `[form=?(%allow %deny) ships=(list ship)]`, where `+form` says whether it's a whitelist or blacklist and `.ships` are the ships on that list.

#### Example

```
> |ames/snub %deny ~wet ~sampel
>=

> .^([form=?(%allow %deny) ships=(list ship)] %ax /=//=/snubbed)
[form=%deny ships=[i=~sampel t=[i=~wet t=~]]]
```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.urbit.org/urbit-os/kernel/ames/scry.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.