Documentation Powered by ReDoc

UTM API (USS->DSS and USS->USS) (0.3.17)

Download OpenAPI specification:Download

Interface definitions for communication between a UAS Service Supplier (USS) and a Discovery and Synchronization Service (DSS), as well as for communication between two USSs.

DSS functionality includes identification of peer UTM USS instances (managing flight operational intents and constraints). USS functionality includes sharing details of flight operational intents and constraints.

Note: Unless otherwise specified, fields specified in a message but not declared in the API must be ignored.

Whenever a object-type field may be omitted, it may also be set to null for the same effect. bbbb

Authentication

Authority

Authorization from, or on behalf of, an authorization authority. This authority will issue access tokens that are JSON Web Tokens as defined in RFC 7519, using the RS256 algorithm for the signature, publish to all providers the public key for verifying that signature, and implement standard OAuth server discovery mechanisms as described in RFC 8414.

The following fields must be included in the JWT claim for access tokens issued by this authority:

  • iss, with the URL at which the token generation request was received.
  • exp, with a time no further than 1 hour in the future.
  • sub, with unique ID of the client requesting the access token.
  • scope, with a string composed of a space-separated list of strings indicating the scopes granted, per RFC 6749.
  • jti, according to RFC 7519.

Following the principle of least privilege, only one of the scopes enumerated in this document should be granted in a single token (though other scopes may accompany it). The tokens granted by this authority must protect against reuse of received tokens to impersonate the sender to other recipients (via use of the aud claim or other means).

When using the aud claim to protect against the reuse of received tokens, and absent guidance on behalf of the competent authority to the contrary, the JWT aud claim requested by the client must be included in each access token and must contain the fully qualified domain name of the URL the access token will be used to access. For example, if a USS were querying the endpoint at https://dss.example.com:8888/rid/v2/dss/identification_service_areas, the access token included in the request should specify "aud": "dss.example.com".

Clients must provide these access tokens in an Authorization header in the form Bearer <token> in accordance with RFC 6750.

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://auth.example.com/oauth/token
Scopes:
  • utm.strategic_coordination -

    Client may perform actions encompassed by the strategic coordination role including strategic conflict detection.

  • utm.constraint_management -

    Client may manage (create, edit, and delete) constraints according to the constraint management role.

  • utm.constraint_processing -

    Client may read constraint references from the DSS and details from the partner USSs according to the constraint processing role.

  • utm.conformance_monitoring_sa -

    Client may perform actions encompassed by the conformance monitoring for situational awareness role.

  • utm.availability_arbitration -

    Client may set the availability state of USSs in the DSS.

Operational intent references

Endpoints exposed by the DSS for interaction with references to operational intents.

Query all operational intent references in the specified area/volume/time from the DSS.

Note that this endpoint does not produce any mutations in the DSS despite using the HTTP POST verb. The HTTP GET verb is traditionally used for operations like this one, but requiring or using a request body for HTTP GET requests is non-standard and not supported by some architectures. POST is used here instead of GET to ensure robust support for the use of a request body.

Authorizations:
Authority (utm.strategic_coordination) Authority (utm.conformance_monitoring_sa)
Request Body schema: application/json
object (Volume4D)

Contiguous block of geographic spacetime.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "operational_intent_references": [ ]
}

Retrieve the specified operational intent reference from the DSS.

Authorizations:
Authority (utm.strategic_coordination) Authority (utm.conformance_monitoring_sa)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the operational intent.

Responses

Response samples

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

Create the specified operational intent reference in the DSS.

Authorizations:
Authority (utm.strategic_coordination) Authority (utm.strategic_coordinationutm.constraint_processing) Authority (utm.conformance_monitoring_sa)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the operational intent.

Request Body schema: application/json
required
Array of objects (Volume4D) non-empty

Spacetime extents that bound this operational intent.

Start and end times, as well as lower and upper altitudes, are required for each volume. The end time may not be in the past. All volumes, both nominal and off-nominal, must be encompassed in these extents. However, these extents do not need to match the precise volumes of the operational intent; a single bounding extent may be provided instead, for instance.

Array of Key (strings)

Proof that the USS creating or mutating this operational intent was aware of the current state of the airspace, with the expectation that this operational intent is therefore deconflicted from all relevant features in the airspace. This field is not required when declaring an operational intent Nonconforming or Contingent, or when there are no relevant Entities in the airspace, but is otherwise required. OVNs for constraints are required if and only if the USS managing this operational intent is performing the constraint processing role, which is indicated by whether the subscription associated with this operational intent triggers notifications for constraints. The key does not need to contain the OVN for the operational intent being updated.

state
required
string (OperationalIntentState)
Enum: "Accepted" "Activated" "Nonconforming" "Contingent"

State of an operational intent.

'Accepted': Operational intent is created and shared, but not yet in use; see standard text for more details.

The create or update request for this operational intent reference must include a Key containing all OVNs for all relevant Entities.

'Activated': Operational intent is in active use; see standard text for more details.

The create or update request for this operational intent reference must include a Key containing all OVNs for all relevant Entities.

'Nonconforming': UA is temporarily outside its volumes, but the situation is expected to be recoverable; see standard text for more details.

In this state, the `/uss/v1/operational_intents/{entityid}/telemetry' USS-USS endpoint should respond, if available, to queries from USS peers. The create or update request for this operational intent may omit a Key in this case because the operational intent is being adjusted as flown and cannot necessarily deconflict.

'Contingent': UA is considered unrecoverably unable to conform with its coordinate operational intent; see standard text for more details.

This state must transition to Ended. In this state, the `/uss/v1/operational_intents/{entityid}/telemetry' USS-USS endpoint should respond, if available, to queries from USS peers. The create or update request for this operational intent may omit a Key in this case because the operational intent is being adjusted as flown and cannot necessarily deconflict.

required
UssBaseURL (string) (OperationalIntentUssBaseURL)

The base URL of a USS implementation that implements the parts of the USS-USS API necessary for providing the details of this operational intent, and telemetry during non-conformance or contingency, if applicable.

EntityID (UUIDv4Format (string))

The ID of an existing subscription that the USS will use to keep the operator informed about updates to relevant airspace information. If this field is not provided, then the new_subscription field must be provided in order to provide notification capability for the operational intent. The subscription specified by this ID must cover at least the area over which this operational intent is conducted, and it must provide notifications for operational intents.

ImplicitSubscriptionParameters (object)

If an existing subscription is not specified in subscription_id, then this field must be populated. When this field is populated, an implicit subscription will be created and associated with this operational intent, and will generally be deleted automatically upon the deletion of this operational intent.

Responses

Request samples

Content type
application/json
{
  • "extents": [
    ],
  • "key": [ ],
  • "state": "Accepted",
  • "uss_base_url": "https://uss.example.com/utm",
  • "subscription_id": "2f8343be-6482-4d1b-a474-16847e01af1e",
  • "new_subscription": {}
}

Response samples

Content type
application/json
{
  • "subscribers": [ ],
  • "operational_intent_reference": {
    }
}

Update the specified operational intent reference in the DSS.

Authorizations:
Authority (utm.strategic_coordination) Authority (utm.strategic_coordinationutm.constraint_processing) Authority (utm.conformance_monitoring_sa)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the operational intent.

ovn
required
string (EntityOVN) [ 16 .. 128 ] characters
Example: 9d158f59-80b7-4c11-9c0c-8a2b4d936b2d

Opaque version number of the existing operational intent reference.

Request Body schema: application/json
required
Array of objects (Volume4D) non-empty

Spacetime extents that bound this operational intent.

Start and end times, as well as lower and upper altitudes, are required for each volume. The end time may not be in the past. All volumes, both nominal and off-nominal, must be encompassed in these extents. However, these extents do not need to match the precise volumes of the operational intent; a single bounding extent may be provided instead, for instance.

Array of Key (strings)

Proof that the USS creating or mutating this operational intent was aware of the current state of the airspace, with the expectation that this operational intent is therefore deconflicted from all relevant features in the airspace. This field is not required when declaring an operational intent Nonconforming or Contingent, or when there are no relevant Entities in the airspace, but is otherwise required. OVNs for constraints are required if and only if the USS managing this operational intent is performing the constraint processing role, which is indicated by whether the subscription associated with this operational intent triggers notifications for constraints. The key does not need to contain the OVN for the operational intent being updated.

state
required
string (OperationalIntentState)
Enum: "Accepted" "Activated" "Nonconforming" "Contingent"

State of an operational intent.

'Accepted': Operational intent is created and shared, but not yet in use; see standard text for more details.

The create or update request for this operational intent reference must include a Key containing all OVNs for all relevant Entities.

'Activated': Operational intent is in active use; see standard text for more details.

The create or update request for this operational intent reference must include a Key containing all OVNs for all relevant Entities.

'Nonconforming': UA is temporarily outside its volumes, but the situation is expected to be recoverable; see standard text for more details.

In this state, the `/uss/v1/operational_intents/{entityid}/telemetry' USS-USS endpoint should respond, if available, to queries from USS peers. The create or update request for this operational intent may omit a Key in this case because the operational intent is being adjusted as flown and cannot necessarily deconflict.

'Contingent': UA is considered unrecoverably unable to conform with its coordinate operational intent; see standard text for more details.

This state must transition to Ended. In this state, the `/uss/v1/operational_intents/{entityid}/telemetry' USS-USS endpoint should respond, if available, to queries from USS peers. The create or update request for this operational intent may omit a Key in this case because the operational intent is being adjusted as flown and cannot necessarily deconflict.

required
UssBaseURL (string) (OperationalIntentUssBaseURL)

The base URL of a USS implementation that implements the parts of the USS-USS API necessary for providing the details of this operational intent, and telemetry during non-conformance or contingency, if applicable.

EntityID (UUIDv4Format (string))

The ID of an existing subscription that the USS will use to keep the operator informed about updates to relevant airspace information. If this field is not provided, then the new_subscription field must be provided in order to provide notification capability for the operational intent. The subscription specified by this ID must cover at least the area over which this operational intent is conducted, and it must provide notifications for operational intents.

ImplicitSubscriptionParameters (object)

If an existing subscription is not specified in subscription_id, then this field must be populated. When this field is populated, an implicit subscription will be created and associated with this operational intent, and will generally be deleted automatically upon the deletion of this operational intent.

Responses

Request samples

Content type
application/json
{
  • "extents": [
    ],
  • "key": [ ],
  • "state": "Accepted",
  • "uss_base_url": "https://uss.example.com/utm",
  • "subscription_id": "2f8343be-6482-4d1b-a474-16847e01af1e",
  • "new_subscription": {}
}

Response samples

Content type
application/json
{
  • "subscribers": [ ],
  • "operational_intent_reference": {
    }
}

Remove the specified operational intent reference from the DSS.

Authorizations:
Authority (utm.strategic_coordination) Authority (utm.conformance_monitoring_sa)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the operational intent.

ovn
required
string (EntityOVN) [ 16 .. 128 ] characters
Example: 9d158f59-80b7-4c11-9c0c-8a2b4d936b2d

Opaque version number of the existing operational intent reference.

Responses

Response samples

Content type
application/json
{
  • "subscribers": [ ],
  • "operational_intent_reference": {
    }
}

Operational intent details

Endpoints exposed by USSs for interaction with details of operational intents.

Retrieve the specified operational intent details from a USS.

The USS hosting this endpoint returns the details (and reference) of an operational intent it manages. While the USS has a pending request to change the operational intent in the DSS, the USS should report the most recent version the USS knows was accepted by the DSS. So, before a USS receives a response to create an operational intent reference in the DSS, it should return 404 if queried for that operational intent at this endpoint.

Authorizations:
Authority (utm.strategic_coordination)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID for this operational intent.

Responses

Response samples

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

Query detailed information on the position of an off-nominal operational intent from a USS.

Authorizations:
Authority (utm.conformance_monitoring_sa)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID for this operational intent.

Responses

Response samples

Content type
application/json
{
  • "operational_intent_id": "2f8343be-6482-4d1b-a474-16847e01af1e",
  • "telemetry": {
    },
  • "next_telemetry_opportunity": {
    }
}

Notify a peer USS of changed operational intent details.

Notify a peer USS directly of changed operational intent details (usually as a requirement of previous interactions with the DSS).

Authorizations:
Authority (utm.strategic_coordination)
Request Body schema: application/json
required
EntityID (UUIDv4Format (string))

ID of operational intent that has changed.

OperationalIntent (object)

Full information about the operational intent that has changed. If this field is omitted, the operational intent was deleted. The ovn field in the nested reference must be populated.

required
Array of objects (SubscriptionState) non-empty

Subscription(s) prompting this notification.

Responses

Request samples

Content type
application/json
{
  • "operational_intent_id": "2f8343be-6482-4d1b-a474-16847e01af1e",
  • "operational_intent": {
    },
  • "subscriptions": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "The error occurred because [...]"
}

Constraint references

Endpoints exposed by the DSS for interaction with references to constraints.

Query all constraint references in the specified area/volume from the DSS.

Note that this endpoint does not produce any mutations in the DSS despite using the HTTP POST verb. The HTTP GET verb is traditionally used for operations like this one, but requiring or using a request body for HTTP GET requests is non-standard and not supported by some architectures. POST is used here instead of GET to ensure robust support for the use of a request body.

Authorizations:
Authority (utm.constraint_management) Authority (utm.constraint_processing)
Request Body schema: application/json
object (Volume4D)

Contiguous block of geographic spacetime.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "constraint_references": [ ]
}

Retrieve the specified constraint reference from the DSS.

Authorizations:
Authority (utm.constraint_management) Authority (utm.constraint_processing)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the constraint.

Responses

Response samples

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

Create the specified constraint reference in the DSS.

Authorizations:
Authority (utm.constraint_management)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the constraint.

Request Body schema: application/json
required
Array of objects (Volume4D) non-empty

Spacetime extents that bound this constraint.

The end time may not be in the past.

All volumes of the constraint must be encompassed in these extents. However, these extents do not need to match the precise volumes of the constraint; a single bounding extent may be provided instead, for instance.

required
UssBaseURL (string) (ConstraintUssBaseURL)

The base URL of a USS implementation that implements the parts of the USS-USS API necessary for providing the details of this constraint.

Responses

Request samples

Content type
application/json
{
  • "extents": [
    ],
  • "uss_base_url": "https://uss.example.com/utm"
}

Response samples

Content type
application/json
{
  • "subscribers": [ ],
  • "constraint_reference": {
    }
}

Update the specified constraint reference in the DSS.

Authorizations:
Authority (utm.constraint_management)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the constraint.

ovn
required
string (EntityOVN) [ 16 .. 128 ] characters
Example: 9d158f59-80b7-4c11-9c0c-8a2b4d936b2d

Opaque version number of the existing operational intent reference.

Request Body schema: application/json
required
Array of objects (Volume4D) non-empty

Spacetime extents that bound this constraint.

The end time may not be in the past.

All volumes of the constraint must be encompassed in these extents. However, these extents do not need to match the precise volumes of the constraint; a single bounding extent may be provided instead, for instance.

required
UssBaseURL (string) (ConstraintUssBaseURL)

The base URL of a USS implementation that implements the parts of the USS-USS API necessary for providing the details of this constraint.

Responses

Request samples

Content type
application/json
{
  • "extents": [
    ],
  • "uss_base_url": "https://uss.example.com/utm"
}

Response samples

Content type
application/json
{
  • "subscribers": [ ],
  • "constraint_reference": {
    }
}

Delete the specified constraint reference from the DSS.

Authorizations:
Authority (utm.constraint_management)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the constraint.

ovn
required
string (EntityOVN) [ 16 .. 128 ] characters
Example: 9d158f59-80b7-4c11-9c0c-8a2b4d936b2d

Opaque version number of the existing operational intent reference.

Responses

Response samples

Content type
application/json
{
  • "subscribers": [ ],
  • "constraint_reference": {
    }
}

Constraint details

Endpoints exposed by USSs for interaction with details of constraints.

Retrieve the specified constraint details from a USS.

The USS hosting this endpoint returns the details (and reference) of a constraint it manages. While the USS has a pending request to change the constraint in the DSS, the USS should report the most recent version the USS knows was accepted by the DSS. So, before a USS receives a response to create a constraint reference in the DSS, it should return 404 if queried for that constraint at this endpoint.

Authorizations:
Authority (utm.constraint_processing)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the constraint.

Responses

Response samples

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

Notify a peer USS of changed constraint details.

Notify a peer USS directly of changed constraint details (usually as a requirement of previous interactions with the DSS).

Authorizations:
Authority (utm.constraint_management)
Request Body schema: application/json
required
EntityID (UUIDv4Format (string))

ID of constraint that has changed.

Constraint (object)

Full information about the constraint that has changed. If this field is omitted, the constraint was deleted. The ovn field in the nested reference must be populated.

required
Array of objects (SubscriptionState) non-empty

Subscription(s) prompting this notification.

Responses

Request samples

Content type
application/json
{
  • "constraint_id": "2f8343be-6482-4d1b-a474-16847e01af1e",
  • "constraint": {
    },
  • "subscriptions": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "The error occurred because [...]"
}

Subscriptions

Endpoints exposed by the DSS for interaction with subscription entities.

Query all subscriptions in the specified area/volume from the DSS.

Query subscriptions intersecting an area of interest. Subscription notifications are only triggered by (and contain full information of) changes to, creation of, or deletion of, Entities referenced by or stored in the DSS; they do not involve any data transfer (such as remote ID telemetry updates) apart from Entity information.

Note that this parameter is a JSON object (in the 'request-body'). Note that either or both of the 'altitude' and 'time' values may be omitted from this parameter.

Only subscriptions belonging to the caller are returned. This endpoint would be used if a USS lost track of subscriptions they had created and/or wanted to resolve an error indicating that they had too many existing subscriptions in an area.

Authorizations:
Authority (utm.constraint_processing) Authority (utm.strategic_coordination)
Request Body schema: application/json
object (Volume4D)

Contiguous block of geographic spacetime.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "subscriptions": [ ]
}

Retrieve the specified subscription from the DSS.

Retrieve a specific subscription.

Authorizations:
Authority (utm.constraint_processing) Authority (utm.strategic_coordination)
path Parameters
required
UUIDv4Format (string) (SubscriptionID)
Example: 78ea3fe8-71c2-4f5c-9b44-9c02f5563c6f

SubscriptionID of the subscription of interest.

Responses

Response samples

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

Create the specified subscription in the DSS.

Create a subscription.

Subscription notifications are only triggered by (and contain full information of) changes to, creation of, or deletion of, Entities referenced by or stored in the DSS; they do not involve any data transfer (such as remote ID telemetry updates) apart from Entity information.

Authorizations:
Authority (utm.constraint_processing) Authority (utm.strategic_coordination)
path Parameters
required
UUIDv4Format (string) (SubscriptionID)
Example: 78ea3fe8-71c2-4f5c-9b44-9c02f5563c6f

SubscriptionID of the subscription of interest.

Request Body schema: application/json
required
Volume4D (object)

Spacetime extents of the volume to subscribe to.

This subscription will automatically be deleted after its end time if it has not been refreshed by then. If end time is not specified, the value will be chosen automatically by the DSS. If start time is not specified, it will default to the time the request is processed. The end time may not be in the past.

Note that some Entities triggering notifications may lie entirely outside the requested area.

required
UssBaseURL (string) (SubscriptionUssBaseURL)

The base URL of a USS implementation of the parts of the USS-USS API necessary for receiving the notifications requested by this subscription.

notify_for_operational_intents
boolean
Default: false

If true, trigger notifications when operational intents are created, updated, or deleted. Otherwise, changes in operational intents should not trigger notifications. The scope utm.strategic_coordination is required to set this flag true.

notify_for_constraints
boolean
Default: false

If true, trigger notifications when constraints are created, updated, or deleted. Otherwise, changes in constraints should not trigger notifications. The scope utm.constraint_processing is required to set this flag true.

Responses

Request samples

Content type
application/json
{
  • "extents": {
    },
  • "uss_base_url": "https://uss.example.com/utm",
  • "notify_for_operational_intents": false,
  • "notify_for_constraints": false
}

Response samples

Content type
application/json
{
  • "subscription": {
    },
  • "operational_intent_references": [ ],
  • "constraint_references": [ ]
}

Update the specified subscription in the DSS.

Update a subscription.

Subscription notifications are only triggered by (and contain full information of) changes to, creation of, or deletion of, Entities referenced by or stored in the DSS; they do not involve any data transfer (such as remote ID telemetry updates) apart from Entity information.

The standard requires each operational intent to have a subscription that cover the 4D volume of the operational intent. If a USS attempts to update a subscription upon which an operational intent depends, and this update would cause the operational intent to lose subscription coverage, the update will be rejected by the DSS as a bad request.

Authorizations:
Authority (utm.constraint_processing) Authority (utm.strategic_coordination)
path Parameters
required
UUIDv4Format (string) (SubscriptionID)
Example: 78ea3fe8-71c2-4f5c-9b44-9c02f5563c6f

SubscriptionID of the subscription of interest.

version
required
string

Version of the subscription to be modified.

Request Body schema: application/json
required
Volume4D (object)

Spacetime extents of the volume to subscribe to.

This subscription will automatically be deleted after its end time if it has not been refreshed by then. If end time is not specified, the value will be chosen automatically by the DSS. If start time is not specified, it will default to the time the request is processed. The end time may not be in the past.

Note that some Entities triggering notifications may lie entirely outside the requested area.

required
UssBaseURL (string) (SubscriptionUssBaseURL)

The base URL of a USS implementation of the parts of the USS-USS API necessary for receiving the notifications requested by this subscription.

notify_for_operational_intents
boolean
Default: false

If true, trigger notifications when operational intents are created, updated, or deleted. Otherwise, changes in operational intents should not trigger notifications. The scope utm.strategic_coordination is required to set this flag true.

notify_for_constraints
boolean
Default: false

If true, trigger notifications when constraints are created, updated, or deleted. Otherwise, changes in constraints should not trigger notifications. The scope utm.constraint_processing is required to set this flag true.

Responses

Request samples

Content type
application/json
{
  • "extents": {
    },
  • "uss_base_url": "https://uss.example.com/utm",
  • "notify_for_operational_intents": false,
  • "notify_for_constraints": false
}

Response samples

Content type
application/json
{
  • "subscription": {
    },
  • "operational_intent_references": [ ],
  • "constraint_references": [ ]
}

Remove the specified subscription from the DSS.

The standard requires each operational intent to have a subscription that cover the 4D volume of the operational intent. If a USS attempts to delete a subscription upon which an operational intent depends, the deletion will be rejected by the DSS as a bad request.

Authorizations:
Authority (utm.constraint_processing) Authority (utm.strategic_coordination)
path Parameters
required
UUIDv4Format (string) (SubscriptionID)
Example: 78ea3fe8-71c2-4f5c-9b44-9c02f5563c6f

SubscriptionID of the subscription of interest.

version
required
string

Version of the subscription to be modified.

Responses

Response samples

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

Reports

Endpoints exposed by the DSS for reporting peer DSS issues.

Report information about communication issues to a DSS.

Report issues to a DSS. Data sent to this endpoint is archived.

Authorizations:
Authority (utm.constraint_management) Authority (utm.constraint_processing) Authority (utm.strategic_coordination) Authority (utm.conformance_monitoring_sa) Authority (utm.availability_arbitration)
Request Body schema: application/json
report_id
string <= 128 characters

ID assigned by the server receiving the report. Not populated when submitting a report.

required
ExchangeRecord (object)

The request (by this USS) and response associated with the error.

Responses

Request samples

Content type
application/json
{
  • "report_id": "string",
  • "exchange": {
    }
}

Response samples

Content type
application/json
{
  • "report_id": "string",
  • "exchange": {
    }
}

Notify USS of an error encountered that might otherwise go unnoticed.

Endpoint to provide feedback (errors, etc.) that might otherwise go unnoticed by this USS. This endpoint is used for all feedback related to operational intents and constraints.

Authorizations:
Authority (utm.strategic_coordination) Authority (utm.constraint_processing) Authority (utm.constraint_management) Authority (utm.conformance_monitoring_sa) Authority (utm.availability_arbitration)
Request Body schema: application/json
report_id
string <= 128 characters

ID assigned by the server receiving the report. Not populated when submitting a report.

required
ExchangeRecord (object)

The request (by this USS) and response associated with the error.

Responses

Request samples

Content type
application/json
{
  • "report_id": "string",
  • "exchange": {
    }
}

Response samples

Content type
application/json
{
  • "report_id": "string",
  • "exchange": {
    }
}

Availability

Endpoints exposed by the DSS for declaring USS availability.

Set availability status of a USS.

Set availability status of a USS.

Authorizations:
Authority (utm.availability_arbitration)
path Parameters
uss_id
required
string

Client ID (matching their sub in access tokens) of the USS to which this availability applies.

Request Body schema: application/json
old_version
required
string
Default: ""

Version of USS's availability to change, for consistent read-modify-write operations and consistent retry behavior.

availability
required
string (UssAvailabilityState)
Enum: "Unknown" "Normal" "Down"

A USS is presumed to be in the Unknown state absent indication otherwise by a USS with availability arbitration scope. Upon determination via availability arbitration, a USS is Down when it does not respond appropriately, and a Down USS may not perform the following operations in the DSS:

  • Create an operational intent in the Accepted or Activated states
  • Modify an operational intent whose new or unchanged state is Accepted or Activated
  • Delete an operational intent

A USS in the Unknown state possesses all the capabilities, within the DSS, of a USS in the Normal state.

Responses

Request samples

Content type
application/json
{
  • "old_version": "",
  • "availability": "Unknown"
}

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": {
    }
}

Get availability status of a USS.

Get availability status of a USS.

Authorizations:
Authority (utm.availability_arbitration) Authority (utm.strategic_coordination) Authority (utm.conformance_monitoring_sa)
path Parameters
uss_id
required
string

Client ID (matching their sub in access tokens) of the USS to which this availability applies.

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": {
    }
}

Logging

Pseudo-endpoints not intended to be implemented literally, but rather to illustrate logging data formats

Get USS logs

A USS will not usually implement this endpoint directly, but rather will be capable of exporting log data in a format equivalent to the response format of this pseudo-endpoint according to the requirements of the standard.

Authorizations:
Authority (utm.strategic_coordinationutm.constraint_managementutm.constraint_processingutm.conformance_monitoring_sautm.availability_arbitration)
path Parameters
log_set_id
required
string
Example: com.example.incident.20200107.v4

USS-defined identifier for a set of log entries. For instance, this ID may refer to all logs associated with a particular reportable incident, or over a time range for the purpose of metric computation.

Responses

Response samples

Content type
application/json
{
  • "messages": [ ],
  • "operator_notifications": [ ],
  • "operator_inputs": [ ],
  • "operator_associations": [ ],
  • "planning_attempts": [ ],
  • "operational_intent_positions": [ ],
  • "constraint_provider_associations": [ ]
}

dss

Endpoints exposed by the DSS server.

Query all operational intent references in the specified area/volume/time from the DSS.

Note that this endpoint does not produce any mutations in the DSS despite using the HTTP POST verb. The HTTP GET verb is traditionally used for operations like this one, but requiring or using a request body for HTTP GET requests is non-standard and not supported by some architectures. POST is used here instead of GET to ensure robust support for the use of a request body.

Authorizations:
Authority (utm.strategic_coordination) Authority (utm.conformance_monitoring_sa)
Request Body schema: application/json
object (Volume4D)

Contiguous block of geographic spacetime.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "operational_intent_references": [ ]
}

Retrieve the specified operational intent reference from the DSS.

Authorizations:
Authority (utm.strategic_coordination) Authority (utm.conformance_monitoring_sa)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the operational intent.

Responses

Response samples

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

Create the specified operational intent reference in the DSS.

Authorizations:
Authority (utm.strategic_coordination) Authority (utm.strategic_coordinationutm.constraint_processing) Authority (utm.conformance_monitoring_sa)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the operational intent.

Request Body schema: application/json
required
Array of objects (Volume4D) non-empty

Spacetime extents that bound this operational intent.

Start and end times, as well as lower and upper altitudes, are required for each volume. The end time may not be in the past. All volumes, both nominal and off-nominal, must be encompassed in these extents. However, these extents do not need to match the precise volumes of the operational intent; a single bounding extent may be provided instead, for instance.

Array of Key (strings)

Proof that the USS creating or mutating this operational intent was aware of the current state of the airspace, with the expectation that this operational intent is therefore deconflicted from all relevant features in the airspace. This field is not required when declaring an operational intent Nonconforming or Contingent, or when there are no relevant Entities in the airspace, but is otherwise required. OVNs for constraints are required if and only if the USS managing this operational intent is performing the constraint processing role, which is indicated by whether the subscription associated with this operational intent triggers notifications for constraints. The key does not need to contain the OVN for the operational intent being updated.

state
required
string (OperationalIntentState)
Enum: "Accepted" "Activated" "Nonconforming" "Contingent"

State of an operational intent.

'Accepted': Operational intent is created and shared, but not yet in use; see standard text for more details.

The create or update request for this operational intent reference must include a Key containing all OVNs for all relevant Entities.

'Activated': Operational intent is in active use; see standard text for more details.

The create or update request for this operational intent reference must include a Key containing all OVNs for all relevant Entities.

'Nonconforming': UA is temporarily outside its volumes, but the situation is expected to be recoverable; see standard text for more details.

In this state, the `/uss/v1/operational_intents/{entityid}/telemetry' USS-USS endpoint should respond, if available, to queries from USS peers. The create or update request for this operational intent may omit a Key in this case because the operational intent is being adjusted as flown and cannot necessarily deconflict.

'Contingent': UA is considered unrecoverably unable to conform with its coordinate operational intent; see standard text for more details.

This state must transition to Ended. In this state, the `/uss/v1/operational_intents/{entityid}/telemetry' USS-USS endpoint should respond, if available, to queries from USS peers. The create or update request for this operational intent may omit a Key in this case because the operational intent is being adjusted as flown and cannot necessarily deconflict.

required
UssBaseURL (string) (OperationalIntentUssBaseURL)

The base URL of a USS implementation that implements the parts of the USS-USS API necessary for providing the details of this operational intent, and telemetry during non-conformance or contingency, if applicable.

EntityID (UUIDv4Format (string))

The ID of an existing subscription that the USS will use to keep the operator informed about updates to relevant airspace information. If this field is not provided, then the new_subscription field must be provided in order to provide notification capability for the operational intent. The subscription specified by this ID must cover at least the area over which this operational intent is conducted, and it must provide notifications for operational intents.

ImplicitSubscriptionParameters (object)

If an existing subscription is not specified in subscription_id, then this field must be populated. When this field is populated, an implicit subscription will be created and associated with this operational intent, and will generally be deleted automatically upon the deletion of this operational intent.

Responses

Request samples

Content type
application/json
{
  • "extents": [
    ],
  • "key": [ ],
  • "state": "Accepted",
  • "uss_base_url": "https://uss.example.com/utm",
  • "subscription_id": "2f8343be-6482-4d1b-a474-16847e01af1e",
  • "new_subscription": {}
}

Response samples

Content type
application/json
{
  • "subscribers": [ ],
  • "operational_intent_reference": {
    }
}

Update the specified operational intent reference in the DSS.

Authorizations:
Authority (utm.strategic_coordination) Authority (utm.strategic_coordinationutm.constraint_processing) Authority (utm.conformance_monitoring_sa)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the operational intent.

ovn
required
string (EntityOVN) [ 16 .. 128 ] characters
Example: 9d158f59-80b7-4c11-9c0c-8a2b4d936b2d

Opaque version number of the existing operational intent reference.

Request Body schema: application/json
required
Array of objects (Volume4D) non-empty

Spacetime extents that bound this operational intent.

Start and end times, as well as lower and upper altitudes, are required for each volume. The end time may not be in the past. All volumes, both nominal and off-nominal, must be encompassed in these extents. However, these extents do not need to match the precise volumes of the operational intent; a single bounding extent may be provided instead, for instance.

Array of Key (strings)

Proof that the USS creating or mutating this operational intent was aware of the current state of the airspace, with the expectation that this operational intent is therefore deconflicted from all relevant features in the airspace. This field is not required when declaring an operational intent Nonconforming or Contingent, or when there are no relevant Entities in the airspace, but is otherwise required. OVNs for constraints are required if and only if the USS managing this operational intent is performing the constraint processing role, which is indicated by whether the subscription associated with this operational intent triggers notifications for constraints. The key does not need to contain the OVN for the operational intent being updated.

state
required
string (OperationalIntentState)
Enum: "Accepted" "Activated" "Nonconforming" "Contingent"

State of an operational intent.

'Accepted': Operational intent is created and shared, but not yet in use; see standard text for more details.

The create or update request for this operational intent reference must include a Key containing all OVNs for all relevant Entities.

'Activated': Operational intent is in active use; see standard text for more details.

The create or update request for this operational intent reference must include a Key containing all OVNs for all relevant Entities.

'Nonconforming': UA is temporarily outside its volumes, but the situation is expected to be recoverable; see standard text for more details.

In this state, the `/uss/v1/operational_intents/{entityid}/telemetry' USS-USS endpoint should respond, if available, to queries from USS peers. The create or update request for this operational intent may omit a Key in this case because the operational intent is being adjusted as flown and cannot necessarily deconflict.

'Contingent': UA is considered unrecoverably unable to conform with its coordinate operational intent; see standard text for more details.

This state must transition to Ended. In this state, the `/uss/v1/operational_intents/{entityid}/telemetry' USS-USS endpoint should respond, if available, to queries from USS peers. The create or update request for this operational intent may omit a Key in this case because the operational intent is being adjusted as flown and cannot necessarily deconflict.

required
UssBaseURL (string) (OperationalIntentUssBaseURL)

The base URL of a USS implementation that implements the parts of the USS-USS API necessary for providing the details of this operational intent, and telemetry during non-conformance or contingency, if applicable.

EntityID (UUIDv4Format (string))

The ID of an existing subscription that the USS will use to keep the operator informed about updates to relevant airspace information. If this field is not provided, then the new_subscription field must be provided in order to provide notification capability for the operational intent. The subscription specified by this ID must cover at least the area over which this operational intent is conducted, and it must provide notifications for operational intents.

ImplicitSubscriptionParameters (object)

If an existing subscription is not specified in subscription_id, then this field must be populated. When this field is populated, an implicit subscription will be created and associated with this operational intent, and will generally be deleted automatically upon the deletion of this operational intent.

Responses

Request samples

Content type
application/json
{
  • "extents": [
    ],
  • "key": [ ],
  • "state": "Accepted",
  • "uss_base_url": "https://uss.example.com/utm",
  • "subscription_id": "2f8343be-6482-4d1b-a474-16847e01af1e",
  • "new_subscription": {}
}

Response samples

Content type
application/json
{
  • "subscribers": [ ],
  • "operational_intent_reference": {
    }
}

Remove the specified operational intent reference from the DSS.

Authorizations:
Authority (utm.strategic_coordination) Authority (utm.conformance_monitoring_sa)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the operational intent.

ovn
required
string (EntityOVN) [ 16 .. 128 ] characters
Example: 9d158f59-80b7-4c11-9c0c-8a2b4d936b2d

Opaque version number of the existing operational intent reference.

Responses

Response samples

Content type
application/json
{
  • "subscribers": [ ],
  • "operational_intent_reference": {
    }
}

Query all constraint references in the specified area/volume from the DSS.

Note that this endpoint does not produce any mutations in the DSS despite using the HTTP POST verb. The HTTP GET verb is traditionally used for operations like this one, but requiring or using a request body for HTTP GET requests is non-standard and not supported by some architectures. POST is used here instead of GET to ensure robust support for the use of a request body.

Authorizations:
Authority (utm.constraint_management) Authority (utm.constraint_processing)
Request Body schema: application/json
object (Volume4D)

Contiguous block of geographic spacetime.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "constraint_references": [ ]
}

Retrieve the specified constraint reference from the DSS.

Authorizations:
Authority (utm.constraint_management) Authority (utm.constraint_processing)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the constraint.

Responses

Response samples

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

Create the specified constraint reference in the DSS.

Authorizations:
Authority (utm.constraint_management)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the constraint.

Request Body schema: application/json
required
Array of objects (Volume4D) non-empty

Spacetime extents that bound this constraint.

The end time may not be in the past.

All volumes of the constraint must be encompassed in these extents. However, these extents do not need to match the precise volumes of the constraint; a single bounding extent may be provided instead, for instance.

required
UssBaseURL (string) (ConstraintUssBaseURL)

The base URL of a USS implementation that implements the parts of the USS-USS API necessary for providing the details of this constraint.

Responses

Request samples

Content type
application/json
{
  • "extents": [
    ],
  • "uss_base_url": "https://uss.example.com/utm"
}

Response samples

Content type
application/json
{
  • "subscribers": [ ],
  • "constraint_reference": {
    }
}

Update the specified constraint reference in the DSS.

Authorizations:
Authority (utm.constraint_management)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the constraint.

ovn
required
string (EntityOVN) [ 16 .. 128 ] characters
Example: 9d158f59-80b7-4c11-9c0c-8a2b4d936b2d

Opaque version number of the existing operational intent reference.

Request Body schema: application/json
required
Array of objects (Volume4D) non-empty

Spacetime extents that bound this constraint.

The end time may not be in the past.

All volumes of the constraint must be encompassed in these extents. However, these extents do not need to match the precise volumes of the constraint; a single bounding extent may be provided instead, for instance.

required
UssBaseURL (string) (ConstraintUssBaseURL)

The base URL of a USS implementation that implements the parts of the USS-USS API necessary for providing the details of this constraint.

Responses

Request samples

Content type
application/json
{
  • "extents": [
    ],
  • "uss_base_url": "https://uss.example.com/utm"
}

Response samples

Content type
application/json
{
  • "subscribers": [ ],
  • "constraint_reference": {
    }
}

Delete the specified constraint reference from the DSS.

Authorizations:
Authority (utm.constraint_management)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the constraint.

ovn
required
string (EntityOVN) [ 16 .. 128 ] characters
Example: 9d158f59-80b7-4c11-9c0c-8a2b4d936b2d

Opaque version number of the existing operational intent reference.

Responses

Response samples

Content type
application/json
{
  • "subscribers": [ ],
  • "constraint_reference": {
    }
}

Query all subscriptions in the specified area/volume from the DSS.

Query subscriptions intersecting an area of interest. Subscription notifications are only triggered by (and contain full information of) changes to, creation of, or deletion of, Entities referenced by or stored in the DSS; they do not involve any data transfer (such as remote ID telemetry updates) apart from Entity information.

Note that this parameter is a JSON object (in the 'request-body'). Note that either or both of the 'altitude' and 'time' values may be omitted from this parameter.

Only subscriptions belonging to the caller are returned. This endpoint would be used if a USS lost track of subscriptions they had created and/or wanted to resolve an error indicating that they had too many existing subscriptions in an area.

Authorizations:
Authority (utm.constraint_processing) Authority (utm.strategic_coordination)
Request Body schema: application/json
object (Volume4D)

Contiguous block of geographic spacetime.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "subscriptions": [ ]
}

Retrieve the specified subscription from the DSS.

Retrieve a specific subscription.

Authorizations:
Authority (utm.constraint_processing) Authority (utm.strategic_coordination)
path Parameters
required
UUIDv4Format (string) (SubscriptionID)
Example: 78ea3fe8-71c2-4f5c-9b44-9c02f5563c6f

SubscriptionID of the subscription of interest.

Responses

Response samples

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

Create the specified subscription in the DSS.

Create a subscription.

Subscription notifications are only triggered by (and contain full information of) changes to, creation of, or deletion of, Entities referenced by or stored in the DSS; they do not involve any data transfer (such as remote ID telemetry updates) apart from Entity information.

Authorizations:
Authority (utm.constraint_processing) Authority (utm.strategic_coordination)
path Parameters
required
UUIDv4Format (string) (SubscriptionID)
Example: 78ea3fe8-71c2-4f5c-9b44-9c02f5563c6f

SubscriptionID of the subscription of interest.

Request Body schema: application/json
required
Volume4D (object)

Spacetime extents of the volume to subscribe to.

This subscription will automatically be deleted after its end time if it has not been refreshed by then. If end time is not specified, the value will be chosen automatically by the DSS. If start time is not specified, it will default to the time the request is processed. The end time may not be in the past.

Note that some Entities triggering notifications may lie entirely outside the requested area.

required
UssBaseURL (string) (SubscriptionUssBaseURL)

The base URL of a USS implementation of the parts of the USS-USS API necessary for receiving the notifications requested by this subscription.

notify_for_operational_intents
boolean
Default: false

If true, trigger notifications when operational intents are created, updated, or deleted. Otherwise, changes in operational intents should not trigger notifications. The scope utm.strategic_coordination is required to set this flag true.

notify_for_constraints
boolean
Default: false

If true, trigger notifications when constraints are created, updated, or deleted. Otherwise, changes in constraints should not trigger notifications. The scope utm.constraint_processing is required to set this flag true.

Responses

Request samples

Content type
application/json
{
  • "extents": {
    },
  • "uss_base_url": "https://uss.example.com/utm",
  • "notify_for_operational_intents": false,
  • "notify_for_constraints": false
}

Response samples

Content type
application/json
{
  • "subscription": {
    },
  • "operational_intent_references": [ ],
  • "constraint_references": [ ]
}

Update the specified subscription in the DSS.

Update a subscription.

Subscription notifications are only triggered by (and contain full information of) changes to, creation of, or deletion of, Entities referenced by or stored in the DSS; they do not involve any data transfer (such as remote ID telemetry updates) apart from Entity information.

The standard requires each operational intent to have a subscription that cover the 4D volume of the operational intent. If a USS attempts to update a subscription upon which an operational intent depends, and this update would cause the operational intent to lose subscription coverage, the update will be rejected by the DSS as a bad request.

Authorizations:
Authority (utm.constraint_processing) Authority (utm.strategic_coordination)
path Parameters
required
UUIDv4Format (string) (SubscriptionID)
Example: 78ea3fe8-71c2-4f5c-9b44-9c02f5563c6f

SubscriptionID of the subscription of interest.

version
required
string

Version of the subscription to be modified.

Request Body schema: application/json
required
Volume4D (object)

Spacetime extents of the volume to subscribe to.

This subscription will automatically be deleted after its end time if it has not been refreshed by then. If end time is not specified, the value will be chosen automatically by the DSS. If start time is not specified, it will default to the time the request is processed. The end time may not be in the past.

Note that some Entities triggering notifications may lie entirely outside the requested area.

required
UssBaseURL (string) (SubscriptionUssBaseURL)

The base URL of a USS implementation of the parts of the USS-USS API necessary for receiving the notifications requested by this subscription.

notify_for_operational_intents
boolean
Default: false

If true, trigger notifications when operational intents are created, updated, or deleted. Otherwise, changes in operational intents should not trigger notifications. The scope utm.strategic_coordination is required to set this flag true.

notify_for_constraints
boolean
Default: false

If true, trigger notifications when constraints are created, updated, or deleted. Otherwise, changes in constraints should not trigger notifications. The scope utm.constraint_processing is required to set this flag true.

Responses

Request samples

Content type
application/json
{
  • "extents": {
    },
  • "uss_base_url": "https://uss.example.com/utm",
  • "notify_for_operational_intents": false,
  • "notify_for_constraints": false
}

Response samples

Content type
application/json
{
  • "subscription": {
    },
  • "operational_intent_references": [ ],
  • "constraint_references": [ ]
}

Remove the specified subscription from the DSS.

The standard requires each operational intent to have a subscription that cover the 4D volume of the operational intent. If a USS attempts to delete a subscription upon which an operational intent depends, the deletion will be rejected by the DSS as a bad request.

Authorizations:
Authority (utm.constraint_processing) Authority (utm.strategic_coordination)
path Parameters
required
UUIDv4Format (string) (SubscriptionID)
Example: 78ea3fe8-71c2-4f5c-9b44-9c02f5563c6f

SubscriptionID of the subscription of interest.

version
required
string

Version of the subscription to be modified.

Responses

Response samples

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

Report information about communication issues to a DSS.

Report issues to a DSS. Data sent to this endpoint is archived.

Authorizations:
Authority (utm.constraint_management) Authority (utm.constraint_processing) Authority (utm.strategic_coordination) Authority (utm.conformance_monitoring_sa) Authority (utm.availability_arbitration)
Request Body schema: application/json
report_id
string <= 128 characters

ID assigned by the server receiving the report. Not populated when submitting a report.

required
ExchangeRecord (object)

The request (by this USS) and response associated with the error.

Responses

Request samples

Content type
application/json
{
  • "report_id": "string",
  • "exchange": {
    }
}

Response samples

Content type
application/json
{
  • "report_id": "string",
  • "exchange": {
    }
}

Set availability status of a USS.

Set availability status of a USS.

Authorizations:
Authority (utm.availability_arbitration)
path Parameters
uss_id
required
string

Client ID (matching their sub in access tokens) of the USS to which this availability applies.

Request Body schema: application/json
old_version
required
string
Default: ""

Version of USS's availability to change, for consistent read-modify-write operations and consistent retry behavior.

availability
required
string (UssAvailabilityState)
Enum: "Unknown" "Normal" "Down"

A USS is presumed to be in the Unknown state absent indication otherwise by a USS with availability arbitration scope. Upon determination via availability arbitration, a USS is Down when it does not respond appropriately, and a Down USS may not perform the following operations in the DSS:

  • Create an operational intent in the Accepted or Activated states
  • Modify an operational intent whose new or unchanged state is Accepted or Activated
  • Delete an operational intent

A USS in the Unknown state possesses all the capabilities, within the DSS, of a USS in the Normal state.

Responses

Request samples

Content type
application/json
{
  • "old_version": "",
  • "availability": "Unknown"
}

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": {
    }
}

Get availability status of a USS.

Get availability status of a USS.

Authorizations:
Authority (utm.availability_arbitration) Authority (utm.strategic_coordination) Authority (utm.conformance_monitoring_sa)
path Parameters
uss_id
required
string

Client ID (matching their sub in access tokens) of the USS to which this availability applies.

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": {
    }
}

p2p_utm

Endpoints exposed by UTM USSs for peer-peer communication.

Retrieve the specified operational intent details from a USS.

The USS hosting this endpoint returns the details (and reference) of an operational intent it manages. While the USS has a pending request to change the operational intent in the DSS, the USS should report the most recent version the USS knows was accepted by the DSS. So, before a USS receives a response to create an operational intent reference in the DSS, it should return 404 if queried for that operational intent at this endpoint.

Authorizations:
Authority (utm.strategic_coordination)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID for this operational intent.

Responses

Response samples

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

Query detailed information on the position of an off-nominal operational intent from a USS.

Authorizations:
Authority (utm.conformance_monitoring_sa)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID for this operational intent.

Responses

Response samples

Content type
application/json
{
  • "operational_intent_id": "2f8343be-6482-4d1b-a474-16847e01af1e",
  • "telemetry": {
    },
  • "next_telemetry_opportunity": {
    }
}

Notify a peer USS of changed operational intent details.

Notify a peer USS directly of changed operational intent details (usually as a requirement of previous interactions with the DSS).

Authorizations:
Authority (utm.strategic_coordination)
Request Body schema: application/json
required
EntityID (UUIDv4Format (string))

ID of operational intent that has changed.

OperationalIntent (object)

Full information about the operational intent that has changed. If this field is omitted, the operational intent was deleted. The ovn field in the nested reference must be populated.

required
Array of objects (SubscriptionState) non-empty

Subscription(s) prompting this notification.

Responses

Request samples

Content type
application/json
{
  • "operational_intent_id": "2f8343be-6482-4d1b-a474-16847e01af1e",
  • "operational_intent": {
    },
  • "subscriptions": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "The error occurred because [...]"
}

Retrieve the specified constraint details from a USS.

The USS hosting this endpoint returns the details (and reference) of a constraint it manages. While the USS has a pending request to change the constraint in the DSS, the USS should report the most recent version the USS knows was accepted by the DSS. So, before a USS receives a response to create a constraint reference in the DSS, it should return 404 if queried for that constraint at this endpoint.

Authorizations:
Authority (utm.constraint_processing)
path Parameters
required
UUIDv4Format (string) (EntityID)
Example: 2f8343be-6482-4d1b-a474-16847e01af1e

EntityID of the constraint.

Responses

Response samples

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

Notify a peer USS of changed constraint details.

Notify a peer USS directly of changed constraint details (usually as a requirement of previous interactions with the DSS).

Authorizations:
Authority (utm.constraint_management)
Request Body schema: application/json
required
EntityID (UUIDv4Format (string))

ID of constraint that has changed.

Constraint (object)

Full information about the constraint that has changed. If this field is omitted, the constraint was deleted. The ovn field in the nested reference must be populated.

required
Array of objects (SubscriptionState) non-empty

Subscription(s) prompting this notification.

Responses

Request samples

Content type
application/json
{
  • "constraint_id": "2f8343be-6482-4d1b-a474-16847e01af1e",
  • "constraint": {
    },
  • "subscriptions": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "The error occurred because [...]"
}

Notify USS of an error encountered that might otherwise go unnoticed.

Endpoint to provide feedback (errors, etc.) that might otherwise go unnoticed by this USS. This endpoint is used for all feedback related to operational intents and constraints.

Authorizations:
Authority (utm.strategic_coordination) Authority (utm.constraint_processing) Authority (utm.constraint_management) Authority (utm.conformance_monitoring_sa) Authority (utm.availability_arbitration)
Request Body schema: application/json
report_id
string <= 128 characters

ID assigned by the server receiving the report. Not populated when submitting a report.

required
ExchangeRecord (object)

The request (by this USS) and response associated with the error.

Responses

Request samples

Content type
application/json
{
  • "report_id": "string",
  • "exchange": {
    }
}

Response samples

Content type
application/json
{
  • "report_id": "string",
  • "exchange": {
    }
}