- EntityService
  - post Create or update an entity (upsert)
  - post Search entities
  - get Get entity by ID

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_basic rdp_jwt rdp_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 Populate what you know - Omit unknown or irrelevant fields Don't invent data - Empty/default values can mislead consumers Use type_info discriminator - Populate the domain-specific section that applies Provenance is critical - Always include source and timestamp Assessment is required for warfighting context - Disposition and environment provide tactical context The authoritative timestamp for entity updates is in `provenance.updated_at`.

### Responses

/api/v1/wdm/entities

### Request samples

- Payload

Content type
application/json
`
{

- "entity":
  {
  - "assessment":
    {
    - "disposition": "DISPOSITION_FRIEND",
    - "environment": "ENVIRONMENT_SURFACE",
    - "nationality": "USA"
    },
  - "description": "Arleigh Burke-class guided missile destroyer",
  - "dimensions":
    {
    - "height_meters": 30,
    - "length_meters": 155,
    - "width_meters": 20
    },
  - "id": "550e8400-e29b-41d4-a716-446655440000",
  - "identities":
    [
    - {
      - "identifier": "366987000",
      - "system": "ais"
      },
    - {
      - "identifier": "366987000",
      - "system": "mmsi"
      }
    ],
  - "labels":
    {
    - "fleet": "7th Fleet",
    - "platform.class": "DDG-51",
    - "platform.hull": "DDG-51"
    },
  - "location":
    {
    - "orientation":
      {
      - "heading_degrees": 45
      },
    - "position":
      {
      - "altitude_hae_meters": 0,
      - "altitude_msl_meters": 0,
      - "latitude_degrees": 35.285,
      - "longitude_degrees": 139.777
      }
    },
  - "motion":
    {
    - "speed_mps": 15.4,
    - "velocity_enu_mps":
      {
      - "x": 10.9,
      - "y": 10.9,
      - "z": 0
      }
    },
  - "name": "USS Arleigh Burke (DDG-51)",
  - "provenance":
    {
    - "name": "ais-receiver-01",
    - "request_id": "9f8d2a3b-4567-89cd-ef01-234567890def",
    - "source": "AIS",
    - "source_node_id": "3c9f7b22-3456-78ab-cdef-234567890abc",
    - "updated_at": "2024-01-15T10:30:00Z"
    },
  - "status": "ENTITY_STATUS_ACTIVE",
  - "type_info":
    {
    - "maritime":
      {
      - "mmsi": "366987000",
      - "nav_status": "NAVIGATION_STATUS_UNDERWAY",
      - "vessel_type": "VESSEL_TYPE_MILITARY"
      }
    }
  }

}`

### Response samples

- 200
- 400
- 401
- 403
- 500
- default

Content type
application/json
`
{

- "entity":
  {
  - "assessment":
    {
    - "disposition": "DISPOSITION_FRIEND",
    - "environment": "ENVIRONMENT_SURFACE"
    },
  - "id": "550e8400-e29b-41d4-a716-446655440000",
  - "location":
    {
    - "position":
      {
      - "altitude_hae_meters": 0,
      - "latitude_degrees": 35,
      - "longitude_degrees": 139
      }
    },
  - "motion":
    {
    - "speed_mps": 15.4
    },
  - "name": "USS Arleigh Burke",
  - "provenance":
    {
    - "source": "AIS",
    - "updated_at": "2024-01-15T10:30:00Z"
    }
  }

}`

## 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_basic rdp_jwt rdp_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

/api/v1/wdm/entities/search

### Request samples

- Payload

Content type
application/json
`
{

- "pageSize": 100,
- "query":
  {
  - "dispositions":
    [
    - "DISPOSITION_FRIEND"
    ],
  - "statuses":
    [
    - "ENTITY_STATUS_ACTIVE"
    ]
  }

}`

### Response samples

- 200
- 400
- 401
- 403
- 500
- default

Content type
application/json
`
{

- "entities":
  [
  - {
    - "assessment":
      {
      - "disposition": "DISPOSITION_FRIEND",
      - "environment": "ENVIRONMENT_SURFACE",
      - "nationality": "USA"
      },
    - "category": "ENTITY_CATEGORY_PLATFORM",
    - "id": "550e8400-e29b-41d4-a716-446655440000",
    - "location":
      {
      - "position":
        {
        - "latitudeDegrees": 35.285,
        - "longitudeDegrees": 139.777
        }
      },
    - "motion":
      {
      - "speedMps": 15.4
      },
    - "name": "USS Arleigh Burke (DDG-51)",
    - "provenance":
      {
      - "name": "ais-receiver-01",
      - "updatedAt": "2024-01-15T10:30:00Z"
      },
    - "status": "ENTITY_STATUS_ACTIVE"
    }
  ],
- "nextCursor": "a2919858-75bf-42c4-8850-2bbb2b94d154"

}`

## Get entity by ID

Retrieves a single entity by its UUID.

##### Authorizations:

rdp_basic rdp_jwt rdp_api_key

##### path Parameters

entityId required | string UUID of the entity to retrieve

### Responses

/api/v1/wdm/entities/{entityId}

### Response samples

- 200
- 400
- 401
- 403
- 404
- 500
- default

Content type
application/json
`
{

- "entity":
  {
  - "assessment":
    {
    - "disposition": "DISPOSITION_FRIEND",
    - "environment": "ENVIRONMENT_SURFACE",
    - "nationality": "USA"
    },
  - "category": "ENTITY_CATEGORY_PLATFORM",
  - "id": "550e8400-e29b-41d4-a716-446655440000",
  - "location":
    {
    - "position":
      {
      - "latitudeDegrees": 35.285,
      - "longitudeDegrees": 139.777
      }
    },
  - "motion":
    {
    - "speedMps": 15.4
    },
  - "name": "USS Arleigh Burke (DDG-51)",
  - "provenance":
    {
    - "name": "ais-receiver-01",
    - "updatedAt": "2024-01-15T10:30:00Z"
    },
  - "status": "ENTITY_STATUS_ACTIVE"
  }

}`