Message Format

GeoSense uses an XML-like syntax for structured content in messages. A wrapping parent node is not required, and messages may mix plain text with XML elements freely.

This format applies to messages on both sides of the conversation — both client requests and agent responses.

Inspect a real message

With Developer Mode on, open the ⋮ menu beside any GeoSense message in the FlyPix app and choose Copy Content. It copies the message's raw markup in exactly this format, the same string the API returns, rather than the rendered text.

Object References

Object references are meant to be treated and rendered as references to the underlying annotation they point to. Generally, the IDs included in a message will belong to one of the vector layers passed along in your send message request.

The agent can, but may not always, include an explicit vector ID reference to narrow down the search space for the annotation. But you should expect and support that they are not included in every reference.

Referential object syntax

<ref id="1" />
<ref id="2" v="af012512-dfb5-02501295283-19ab92c90de2" />
<ref id="3" />, <ref id="5" v="1251-abc9" />, <ref id="62" />

note

There exists a legacy format which you may occasionally receive. This is slowly being phased out. If you are sending messages with explicit annotation references, prefer the syntax above.

Legacy <id> object format

<id>1</id>
<ids>1, 2, 3</ids>
<id v="1234-abcd">1</id>
<ids v="1234-abcd">1, 2, 3, 4</ids>

Class and Layer References

The agent can reference annotation classes and vector layers inline within a message. These render as compact badges that give the user a quick visual cue and a way to interact with the referenced item.

Class References

A class reference renders as a pill-shaped badge coloured to match the class. The id attribute must be the class ID. An optional text body overrides the display name; if omitted, the class name is used instead.

Hovering over the badge highlights all visible annotations belonging to that class on the map.

Class IDs are only unique within a project, so the badge has to work out which project's class is meant. The optional project attribute names it directly, and is always used when present. Without it, the class is looked up in these projects, in order, and the first one that holds it is used:

1. The projects of the annotations, regions and layers referenced elsewhere in the same message.
2. The session's project, then the projects of the layers the session was sent, then the project of the workspace the user has open.

Pass project whenever a message mentions a class on its own, with nothing else in the message that points to its project.

<class> blocks

<class id="classid-1234" />
<class id="classid-1234">Vegetation</class>
<class id="classid-1234" project="project-5678-efgh">Vegetation</class>

Layer References

A vector layer reference renders as an inline badge with an icon that reflects the layer's source (annotated or inference). The id attribute must be the vector ID. An optional text body overrides the display name; if omitted, the layer name is used.

Clicking the badge selects that layer as the active vector.

<vector> blocks

<vector id="1234-abcd" />
<vector id="1234-abcd">Training Layer</vector>

Property Displays

Property displays can generally either be referential or direct.

Referential displays are meant to represent (and display) the value of a certain property of an annotation. On a client application, this annotation should be resolved in the same way as that of the <ref> block above and the property extracted for interactive display.

Value displays are a bit more straightforward, instead of pointing at an existing annotation, they simply display a fixed value. This exists for you to decide how certain common values should be formatted for the user, or to include relevant widgets.

<area> blocks

<area id="1" />
<area id="1" v="1234-abcd" />
<area value="8295125" />
<pixels value="1521234" />

<confidence> blocks

<confidence id="1" />
<confidence id="1" v="1234-abcd" />
<!-- No value block. These are just percentages -->

<angle> block

<angle id="1" />
<angle id="2" v="1234-abcd" />
<angle value="250deg" />
<angle value="-85 deg" />
<angle value="1.62314" /> <!-- No 'deg' implies radians -->

<credits> block

<!-- No referential blocks, annotations don't have credit values -->
<credits value="1.25" />
<credits value="200" />

Position

Position nodes are quite unique in that there are multiple ways to both represent the position of an annotation. In most cases, all results should be fairly close; but the agent may still want to be specific.

For referential position blocks, an optional mode may be included to specify which type of position should be calculated for an annotation.

It will either be center, centroid or the circumcenter.

For direct position blocks, the value will be given generally in mercator coordinates as an <X>, <Y> pair. But we explicitly support a number of formats that you may want to support as well. A few examples are included below.

In general, you will receive two numbers, separated by a comma and/or a space. They may also have cardinal direction indicators instead of sign, and they may include a degree symbol.

For cases where the system is ambiguous, it may be expressly indicated as an extra XML attribute in the <pos> block.

<position> blocks

<pos id="1" />
<pos id="1" v="1234-abcd" />
<pos id="1" mode="centroid" />
<pos value="103.59258102, -13.251208883" />
<pos value="103.59258102E 13.251208883S" />
<pos value="259875.25928,-828521.502093" system="mercator" />
<pos value="-6.2512213 105.0502912" system="latlon" />

Size

Size is quite similar to position nodes, where referential nodes may include a mode.

This mode will be one of: length, thickness width, or height.

These are meant to be represented as longitudinal magnitudes.

<size> blocks

<size id="1" />
<size id="1" v="1234-abcd" />
<size id="1" mode="width" />
<size value="0.52" />

Rich Text

Rich text is fairly straightforward and mirrors HTML:

<b>bold text</b>
<i>italic text</i>
<u>underlined text</u>
<sub>subscript text</sub>
<super>superscript text</super>

warning

Semantic HTML rich text nodes such as <em> or <strong> are not generally supported.

Links

Links are textual blocks which reference some page (external or internal) or entity.

There are multiple types of links, each made for different purposes and with different rules for routing.

Plain Anchors

Plain links can link to internal or external pages following regular HTML anchor rules. A path starting with / is considered internal and absolute. Anchors must have content.

<a href="/datasets">the Datasets page</a>
<a href="/workspace/project-1234-abcd/view/files/raster-1234-abcd">this file</a>
<a href="https://en.wikipedia.org/wiki/Fibonacci_sequence">Fibonacci numbers</a>

Docs Anchors

While links to documentation pages could use a plain <a> tag, the special <docs> anchor is preferred for stylistic reasons and better references. These tags use path instead of href, which is an absolute path from the documentation root — the host or domain should not be included. Content is optional; a contentless <docs> anchor carries no inferred text.

<docs path="/docs/guides/ai/geosense">Learn About Geosense</docs>
<docs path="/blog/2026-05-06-release-v3.2.5">View Changelog</docs>
<docs path="/docs/api/geosense/message-format" />

Entity Links

Entity links are direct references to entities within the app. They require two attributes: type and id.

Valid entity types are: raster, workspace, model, dataset, frozen-dataset, folder, map, project, training, inference, order, region, annotation, and class.

For entities not contained within the project the session belongs to — except for project and map entities — a project attribute must also be provided with the ID of the containing project. Official models use the reserved value "official" as the project ID.

Entity links auto-infer a display name when their content is left empty.

<link type="raster" id="1234-abcd" />                              // auto-inferred name
<link type="raster" id="1234-abcd">Example Raster</link>
<link type="raster" id="ab82-041e" project="6525-02fa" />          // external raster
<link type="model" id="512d-12c3">Your Trees Model</link>
<link type="model" id="05c2-952a" project="6525-02fa" />           // external model
<link type="model" id="ffff-0001" project="official" />            // official model
<link type="workspace" id="958b-ca8f">
  A workspace containing your desertification analysis rasters
</link>
<link type="dataset" id="5120-abcd" />
<link type="frozen-dataset" id="592a-195b" />
<link type="folder" id="6a8f-80bb" project="bab9-f002">Your external folder</link>
<link type="map" id="829c-dd12" />
<link type="project" id="25bd-bd2a" />
<link type="training" id="7c1e-04ab" />
<link type="inference" id="3f9a-77d1">Last week's tree count</link>
<link type="order" id="b20c-91fe">Spring imagery</link>

Some types link somewhere other than the entity's own page, or have none:

Type	Display name	Opens
training	The trained model's name	The frozen dataset it trained on; nothing for a training run straight on a raster
inference	The inference's title	The raster it ran on, as a raster link would
order	The order's ID, so prefer giving a label	The order in the Data Market

Workspace-Only Entities

Regions and annotations only exist on a raster, so they show up on the map, not on a page of their own.

• region renders the region's outline, followed by the link's content when it has any. Hovering it highlights the region on the map. Its tooltip shows the region's name, training and inference behavior, and description.
• annotation is another spelling of the <ref> block, and its id must be numeric. Like <ref>, it accepts a v attribute and ignores any content.
• class is another spelling of the <class> block, and accepts the same project attribute and label.

Clicking a region or an annotation brings it into view in the open workspace, if that workspace can show its raster:

• If the raster is already on screen, the map pans to the region or annotation and selects it.
• If the raster is in another scene, or can be added as a new scene, the workspace switches to it first and focuses on the region or annotation.
• A region is drawn only in the mode that matches its training behavior (Train mode for a training region, View mode otherwise), so the workspace switches to that mode first when needed.

Otherwise the user is asked whether to view it in a workspace of its own, which opens on the raster with the region or annotation in focus.

<link type="region" id="e41b-9c02" />
<link type="region" id="e41b-9c02">the northern field</link>
<link type="annotation" id="1532" v="1251-abc9" />                 // same as <ref id="1532" v="1251-abc9" />
<link type="class" id="classid-1234">Vegetation</link>             // same as <class id="classid-1234">Vegetation</class>

Structural Blocks

Structural blocks allow the agent to distribute or present information in specific ways. These are some commonly used blocks used to structure information.

Paragraph Blocks

<p>This is a paragraph of text.</p>

Paragraphs are also automatically injected by the renderer: a newline in plain text creates a new paragraph, and any non-inline block (such as a table or list) also terminates the current paragraph and starts a new one.

Quote Blocks

<quote>
  This is a quote
</quote>

Code Blocks

<code lang="py">
  # This is how you make a call to our API
  import requests

  api_url = "api.flypix.ai/v1"
  result = requests.get(f"{api_url}/vectors/abcd-1234")
  return result
</code>

Ordered List

<ol>
  <li>First item</li>
  <li>Second item</li>
</ol>

Unordered List

<ul>
  <li>First item</li>
  <li>Second item</li>
</ul>

Tables

<table>
  <tr>
    <th>Annotation ID</th> <th>Area</th> <th>Confidence</th>
  </tr>
  <tr>
    <td><id>1</id></td> <td><area id="1" /></td>
    <td><confidence id="1" /></td>
  </tr>
  <tr>
    <td><id>5</id></td> <td><area id="5" /></td>
    <td><confidence id="5" /></td>
  </tr>
</table>