get_item
Return the full context card for one item.
``url`` is the JSON URL of an open-data STAC sidecar, a GEC/SICD (or other
product) filename such as ``2025-05-17-17-43-46_UMBRA-08_GEC.tif``, or the
acquisition stem ``2025-05-17-17-43-46_UMBRA-08``. A filename or stem is
resolved through the local catalog index: the stem is matched against
asset hrefs, which is what distinguishes ``sar-data/tasks/``,
``sar-data/task-data/``, and ``open-data/`` — the name itself does not.
Zero matches is an error. More than one match lists the candidate STAC
URLs; pass one of those. The hosted server resolves a filename or stem
with the catalog index it already loaded. A local server does the same
after ``umbra index fetch``.
When the index contains a STAC URL, the indexed snapshot is returned —
the same document ``search_catalog`` already answered from — rather than
a live re-fetch that can disagree on asset filenames or product types.
When the server is configured with a token (``$UMBRA_CANOPY_TOKEN``) and
``url`` is a bare acquisition id (no ``://``, and not a filename or stem),
it is instead looked up in Umbra's authenticated commercial archive by a
keyed STAC search — the retrieval complement to ``search_catalog`` over
the paid catalog, since archive cards carry an ``id`` (not a fetchable
sidecar URL) as their hand-off pointer. A filename or stem still resolves
from the local open-data index when a token is set.
On the public host a URL is fetched only when it is https on Umbra's
public open-data bucket. Any other URL is refused before a request.
A bare id that is not in the local index is refused the same way.
The card (:meth:`UmbraItem.to_llm_context`) carries the id, ISO datetime,
place, bbox, resolution, polarization *with the change-detection caveat*,
the per-product-type explanations and asset URLs, and the mandatory
attribution line — everything a model needs to reason about the scene.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"url": "<url>"
},
"name": "get_item"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | STAC JSON URL, product filename, acquisition stem, or — when a Canopy token is set — a bare commercial-archive id. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||