API docs by Redocly

Raft Warfighting Data Model (WDM) Entity Service API (1.0)

Download OpenAPI specification:

REST API for managing entity lifecycle and real-time updates in the Raft Warfighting Data Model (WDM). Provides operations for creating, updating, querying, and streaming entities representing tracked objects in the battlespace (platforms, units, facilities, personnel, etc.).

Note: Streaming APIs (PublishEntities, StreamEntities) are only available via gRPC and are not supported over standard REST/HTTP at this time.

EntityService

Create or update an entity (upsert)

Upsert operation for entities. If entity.id is provided and exists, performs an update; otherwise creates a new entity with a generated UUID.

This single endpoint handles all entity lifecycle operations:

  • CREATE: Omit entity.id or provide a new UUID
  • UPDATE: Provide existing entity.id with modified fields
  • DELETE: Set entity.status to ENTITY_STATUS_DELETED
Authorizations:
rdp_basicrdp_jwtrdp_api_key
Request Body schema: application/json
required

Request body for creating or updating an entity. Note: The 'ontology' field is read-only and will be ignored if provided.

required
object (v1Entity)

Core representation of a tracked object in the battlespace.

An Entity is anything with identity that warfighters need to track: platforms, units, facilities, equipment, personnel, events, control measures, etc.

Flexible Field Model

Entities use a field-optional design rather than strict entity subtypes. Most fields are optional - populate only what is relevant for the specific entity being represented. This flexibility allows the schema to represent diverse entity types without requiring separate message definitions for each category.

Different entity types naturally use different field subsets:

  • Maritime vessel: location, motion, maritime info, identities (MMSI), dimensions
  • Aircraft: location, motion, aviation info, identities (Mode-S), assessment
  • Ground vehicle: location, motion, ground info, assessment, labels
  • Facility: location, dimensions, assessment (no motion)
  • Person: location, assessment (minimal fields)
  • Control measure: shape (or geometry), assessment, labels (no motion/dimensions)
  • Event: location, provenance, description (transient, no motion)

Required vs Optional Fields

Minimally required for all entities:

  • id: Unique identifier (generated if not provided)
  • provenance.updated_at: When this data was last modified

Commonly populated but optional:

  • name: Human-readable identifier
  • location.position: Geographic coordinates
  • assessment: Tactical assessment (disposition, environment)

Domain-specific (populate as applicable):

  • type_info.maritime: For ships, boats, submarines
  • type_info.aviation: For aircraft, helicopters, UAVs
  • type_info.ground: For vehicles, dismounts, equipment
  • type_info.orbital: For satellites, space objects
  • type_info.signal: For SIGINT/ELINT emissions

Motion-related (omit for stationary entities):

  • motion: Velocity and acceleration (platforms in motion)
  • orbital_motion: Keplerian elements (satellites)
  • state_vector: Position and velocity vectors (high-precision orbital)

Specialized use cases:

  • shape: Structured geometry (polygons, ellipses, circles, polylines)
  • geometry: Extended spatial representation as WKT string
  • targeting: When entity is a potential target
  • dimensions: Physical measurements when known
  • details: System-specific extensions

Examples by Entity Type

Naval vessel (comprehensive):

{
  "id": "...", "name": "USS Arleigh Burke", "location": {...}, "motion": {...},
  "type_info": {"maritime": {"vessel_type": "MILITARY", "mmsi": "..."}},
  "assessment": {"disposition": "FRIEND", "environment": "SURFACE"},
  "dimensions": {...}, "provenance": {...}
}

Aircraft (typical):

{
  "id": "...", "name": "REACH 421", "location": {...}, "motion": {...},
  "type_info": {"aviation": {"aircraft_type": "C-17A", "callsign": "REACH421"}},
  "assessment": {"disposition": "FRIEND"}, "provenance": {...}
}

Ground vehicle (minimal):

{
  "id": "...", "location": {...}, "motion": {...},
  "assessment": {"disposition": "HOSTILE", "environment": "SURFACE"},
  "provenance": {...}
}

Facility (no motion):

{
  "id": "...", "name": "FOB Lightning", "location": {...},
  "assessment": {"disposition": "FRIEND"}, "dimensions": {...},
  "provenance": {...}
}

Event (transient):

{
  "id": "...", "name": "IED Strike", "description": "Vehicle-borne IED...",
  "location": {...}, "provenance": {...}
}

Field Population Guidelines

  1. Populate what you know - Omit unknown or irrelevant fields
  2. Don't invent data - Empty/default values can mislead consumers
  3. Use type_info discriminator - Populate the domain-specific section that applies
  4. Provenance is critical - Always include source and timestamp
  5. Assessment is required for warfighting context - Disposition and environment provide tactical context

The authoritative timestamp for entity updates is in provenance.updated_at.

Responses

Request samples

Content type
application/json
{
  • "entity": {
    }
}

Response samples

Content type
application/json
{
  • "entity": {
    }
}

Search entities

Retrieves a paginated list of entities matching the specified filter criteria. Returns a snapshot at query time. For real-time updates, use StreamEntities.

Authorizations:
rdp_basicrdp_jwtrdp_api_key
Request Body schema: application/json
required

Request message for retrieving multiple entities.

object (v1EntityQuery)

Query criteria for retrieving entities from storage.

Uses a flat structure where all criteria are combined with AND logic between fields, and OR logic within repeated fields. Optimized for efficient bulk retrieval. Empty query returns all entities.

For complex filtering (geographic bounding boxes, labels, nested boolean logic), stream entities and use EntityStreamFilter instead.

Logic semantics:

  • Multiple values within a repeated field use OR (e.g., categories=[1,2] means category=1 OR category=2)
  • Different fields are combined with AND (e.g., categories=[1] AND dispositions=[7])

Examples:

Query hostile platforms:

{
  "categories": [1],
  "dispositions": [7]
}

Matches: category=PLATFORM AND disposition=HOSTILE

Query platforms or units that are hostile:

{
  "categories": [1, 2],
  "dispositions": [7]
}

Matches: (category=PLATFORM OR category=UNIT) AND disposition=HOSTILE

Query non-simulated surface entities:

{
  "environments": [5],
  "flags": { "is_simulated": false }
}

Query entities from specific sources:

{
  "provenance": {
    "source_names": ["USS Roosevelt CIC", "SIGINT Station Alpha"]
  }
}

Query entities updated recently:

{
  "provenance": {
    "updated_at": {
      "start": "2025-12-18T10:00:00Z"
    }
  }
}
cursor
string

Pagination cursor from previous response. Omit or leave empty for first page.

pageSize
integer <int32> <= 1000
Default: "10"

Maximum number of entities per page.

Responses

Request samples

Content type
application/json
{
  • "pageSize": 100,
  • "query": {
    }
}

Response samples

Content type
application/json
{
  • "entities": [
    ],
  • "nextCursor": "a2919858-75bf-42c4-8850-2bbb2b94d154"
}

Get entity by ID

Retrieves a single entity by its UUID.

Authorizations:
rdp_basicrdp_jwtrdp_api_key
path Parameters
entityId
required
string

UUID of the entity to retrieve

Responses

Response samples

Content type
application/json
{
  • "entity": {
    }
}