Chapter 6 — APIs Your USS Must Implement

This chapter describes all the HTTP endpoints that your USS must expose publicly. These are the endpoints that DECEA and other USSs will call against your server. They are divided into:

1. Production endpoints — required for all live operations.
2. Testing/Homologation endpoints — required for the validation process.

All endpoints must be accessible over HTTPS from the public internet. The base domain of your server becomes the uss_base_url registered in the DSS.

6.1 Production Endpoints (USS-to-USS)

These are defined in utm.yaml and remoteid.yaml and must be live during production operations.

6.1.1 GET /uss/v1/operational_intents/{entityid}

Purpose: Return the full details of one of your USS's Operational Intents to another USS or DECEA that is querying it.

Required scope (caller must have): utm.strategic_coordination

Response body:

{
  "operational_intent": {
    "reference": {
      "id": "2f8343be-6482-4d1b-a474-16847e01af1e",
      "manager": "your-uss-sub",
      "uss_availability": "Normal",
      "version": 3,
      "state": "Activated",
      "ovn": "9d158f59-80b7-4c11-9c0c-8a2b4d936b2d",
      "time_start": { "value": "2026-07-01T10:00:00Z", "format": "RFC3339" },
      "time_end": { "value": "2026-07-01T11:00:00Z", "format": "RFC3339" },
      "uss_base_url": "https://uss.yourcompany.com/utm",
      "subscription_id": "78ea3fe8-..."
    },
    "details": {
      "volumes": [ ... ],
      "off_nominal_volumes": [],
      "priority": 0,
      "flight_type": "BVLOS"
    }
  }
}

Key behaviors:

• The ovn in the reference is what other USSs collect to include in their key array.
• When the OIR is in Nonconforming or Contingent state, the off_nominal_volumes field must be populated.
• In Contingent state, volumes may be empty (only off_nominal_volumes applies).

6.1.2 POST /uss/v1/operational_intents

Purpose: Receive notifications from other USSs about Operational Intents in your subscription area. This is how you learn about new, updated, or deleted OIRs near your operations.

Required scope (caller must have): utm.strategic_coordination

Request body (OIR created or updated):

{
  "operational_intent_id": "2f8343be-6482-4d1b-a474-16847e01af1e",
  "operational_intent": {
    "reference": { ... },
    "details": {
      "volumes": [ ... ],
      "off_nominal_volumes": [],
      "priority": 0
    }
  },
  "subscriptions": [
    {
      "subscription_id": "78ea3fe8-...",
      "notification_index": 3
    }
  ]
}

Request body (OIR deleted):

{
  "operational_intent_id": "2f8343be-6482-4d1b-a474-16847e01af1e",
  "subscriptions": [
    {
      "subscription_id": "78ea3fe8-...",
      "notification_index": 5
    }
  ]
}

When operational_intent is absent, the OIR has been deleted.

Expected response: 204 No Content

Key behaviors:

• Update your internal airspace state upon receiving this notification.
• Check whether the new/updated OIR or the deletion changes your own conflict situation.
• If a new high-priority OIR or Constraint conflicts with your active operation, begin deconfliction.

6.1.3 GET /uss/v1/constraints/{entityid}

Purpose: Return the full details of a Constraint managed by your USS. In Phase 1, only DECEA creates Constraints, so this endpoint is primarily implemented by DECEA's USS. However, it must also be implemented by all USSs for completeness and future phases.

Required scope (caller must have): utm.constraint_processing

Response body:

{
  "constraint": {
    "reference": {
      "id": "c036326c-...",
      "manager": "decea-uss",
      "version": 1,
      "ovn": "a1b2c3d4-...",
      "time_start": { "value": "2026-07-01T08:00:00Z", "format": "RFC3339" },
      "time_end": { "value": "2026-07-01T20:00:00Z", "format": "RFC3339" },
      "uss_base_url": "https://uss.decea.mil.br/utm"
    },
    "details": {
      "volumes": [ ... ],
      "type": "com.decea.restricted_area"
    }
  }
}

6.1.4 POST /uss/v1/constraints

Purpose: Receive notifications about new, updated, or deleted Constraints in your subscription area. These come from DECEA's USS (and in future phases, potentially other authorized entities).

Required scope (caller must have): utm.constraint_management

Request body (Constraint notification):

{
  "constraint_id": "c036326c-...",
  "constraint": {
    "reference": { ... },
    "details": { "volumes": [ ... ], "type": "..." }
  },
  "subscriptions": [
    { "subscription_id": "...", "notification_index": 1 }
  ]
}

When constraint is absent, the Constraint has been deleted.

Expected response: 204 No Content

6.1.5 GET /uss/v1/operational_intents/{entityid}/telemetry

Purpose: Serve live telemetry for an OIR in Nonconforming or Contingent state. DECEA's monitoring systems and other USSs call this to track a drone that has deviated from its plan.

Required scope (caller must have): utm.conformance_monitoring_sa

Response body:

{
  "telemetry": {
    "time_measured": { "value": "2026-07-01T10:32:15Z", "format": "RFC3339" },
    "position": {
      "longitude": -45.876,
      "latitude": -23.210,
      "altitude": { "value": 115.2, "reference": "W84", "units": "M" },
      "accuracy_h": "HA10m",
      "accuracy_v": "VA10m"
    },
    "velocity": {
      "speed": 8.5,
      "units_speed": "MetersPerSecond",
      "track": 270.0
    }
  },
  "next_telemetry_opportunity": { "value": "2026-07-01T10:32:25Z", "format": "RFC3339" }
}

This endpoint must only be available when the OIR is in Nonconforming or Contingent state. You may return 404 in other states.

6.1.6 GET /uss/flights

Purpose: Return basic flight information for all active drones in a given geographic view area. This is the primary Remote ID polling endpoint.

Required scope (caller must have): rid.display_provider

Query parameters:

• view — Bounding box as lat1,lng1,lat2,lng2 (southwest and northeast corners).
• recent_positions_duration — How many seconds of recent position history to include (optional).

Response body:

{
  "timestamp": { "value": "2026-07-01T10:32:15Z", "format": "RFC3339" },
  "flights": [
    {
      "id": "flight-uuid-here",
      "aircraft_type": "Helicopter",
      "current_state": {
        "timestamp": { "value": "2026-07-01T10:32:15Z", "format": "RFC3339" },
        "timestamp_accuracy": 0.1,
        "position": {
          "lat": -23.2071,
          "lng": -45.8750,
          "alt": 115.2,
          "accuracy_h": "HA10m",
          "accuracy_v": "VA10m",
          "extrapolated": false
        },
        "track": 270.0,
        "speed": 8.5,
        "speed_accuracy": "SA3mps",
        "vertical_speed": 0.0,
        "operational_status": "Airborne"
      },
      "recent_positions": [ ... ]
    }
  ],
  "no_isas_present": false
}

Update frequency: The data returned must reflect the drone's actual position, updated at most every 10 seconds.

6.1.7 GET /uss/flights/{id}/details

Purpose: Return detailed information for a specific flight, including UAS identification and operator data.

Required scope (caller must have): rid.display_provider

Response body:

{
  "details": {
    "id": "flight-uuid-here",
    "uas_id": {
      "registration_id": "PR-XXXX"
    },
    "operator_id": "operator-registration-id",
    "operator_location": {
      "position": { "lat": -23.208, "lng": -45.878 },
      "altitude": { "value": 0, "reference": "W84", "units": "M" }
    },
    "operation_description": "Package delivery - Sector A",
    "auth_data": {
      "format": 0,
      "data": ""
    }
  }
}

6.2 Additional Required Endpoints

These endpoints are required by the qualification rules (uss-qualification-rules.md) and are called during homologation testing and normal operations.

6.2.1 GET /version

Purpose: Return the current deployed version of your USS software.

No authentication required (or use your standard validation).

Response body:

{
  "version": "1.4.2"
}

6.2.2 GET /diagnostics/time

Purpose: Return the current system time and NTP synchronization status. Used by DECEA to verify your system clock is properly synchronized.

Response body:

{
  "system_time": "2026-07-01T10:32:15.482Z",
  "ntp_sync": {
    "synchronized": true,
    "source": "ntp.decea.gov.br",
    "stratum": 2,
    "offset_ms": 38,
    "last_sync": "2026-07-01T10:32:05.000Z"
  },
  "timestamp_format": "ISO 8601"
}

6.2.3 POST /telemetry

Purpose: Accept drone telemetry data injection during DECEA's homologation testing. DECEA uses this to simulate drone position updates and test your conformance monitoring logic.

Request body:

{
  "flight_id": "a8c4af2a-6640-41d9-b8e7-719fd19a2fce",
  "aircraft_type": "Helicopter",
  "operational_intent_id": "<id-of-the-operational-intent>",
  "position": {
    "timestamp": { "value": "2026-07-01T10:32:00Z", "format": "RFC3339" },
    "lat": -23.207184,
    "lng": -45.875054,
    "alt": 115.0,
    "accuracy_h": "HA10m",
    "accuracy_v": "VA10m",
    "extrapolated": false
  },
  "operational_status": "Airborne",
  "track": 270.0,
  "speed": 10.0,
  "vertical_speed": 0.0,
  "test_metadata": {
    "scenario_id": "VOL4D-EXIT-REENTRY-59S",
    "event": "exit_volume",
    "t_offset_seconds": 0
  }
}

6.3 Homologation/Testing Endpoints

These endpoints are defined in flights.yaml, injection.yaml, and versioning.yaml. They are only called by DECEA's automated testing framework during homologation. You implement them, but they are not used in production operations.

6.3.1 Flight Planning Testing (flights.yaml)

These endpoints simulate the user experience of creating and managing flight plans, allowing DECEA's test framework to exercise your OIR creation and management logic.

Scopes:

• interuss.flight_planning.direct_automated_test — For test director operations (clear area, delete, status).
• interuss.flight_planning.plan — For virtual user operations (create/update, notifications).

6.3.2 Remote ID Data Injection (injection.yaml)

These endpoints allow DECEA's test framework to inject simulated drone telemetry directly into your USS, to test your Remote ID serving logic.

Scope: rid.inject_test_data

Example injection request:

{
  "requested_flights": [
    {
      "injection_id": "test-flight-001",
      "aircraft_type": "Helicopter",
      "telemetry": [
        {
          "timestamp": { "value": "2026-07-01T10:00:00Z", "format": "RFC3339" },
          "position": { "lat": -23.2071, "lng": -45.8750, "alt": 100.0 },
          "track": 90.0,
          "speed": 10.0,
          "vertical_speed": 0.0,
          "operational_status": "Airborne",
          "accuracy_h": "HA10m",
          "accuracy_v": "VA10m"
        }
      ],
      "details_responses": [
        {
          "effective_after": "2026-07-01T09:59:00Z",
          "details": {
            "id": "test-flight-001",
            "operator_id": "OP-TEST-123",
            "uas_id": { "registration_id": "PR-TEST01" }
          }
        }
      ]
    }
  ]
}

6.3.3 Versioning (versioning.yaml)

Scope: interuss.versioning.read_system_versions

Example:

GET /versions/br.mil.decea.brutm.uss.v1

{
  "system_identity": "br.mil.decea.brutm.uss.v1",
  "system_version": "1.4.2"
}

6.4 Summary of All Required Endpoints