Architectural Alias: Ownership and transfer operations in this file are simplified shortcuts for the unified Resource Memberships API. They provide a context-aware view for fleet management.

Access: org_type = Asset Owner, Member+ for reads. Asset must be actively owned by the requesting org. See access-control.md.

Asset Endpoints Summary

Create Asset

POST /assets

Register a single asset (UIN and Model reference) under the organisation.

Request Body:

{
  "asset_uin": "UIN-IND-01239X",
  "uin_status": 0,
  "asset_org_internal_uuid": "ORG-DRN-001",
  "asset_model_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55",
  "org_owner_uuid": "9f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "source": 1,
  "active_payload_uuids": [
    "f8e9d0c1-b2a3-4455-6677-889900aabbcc"
  ]
}

Responses:

• 201 Created:

{
  "message": "Asset registered successfully",
  "data": {
    ...
  }
}

• 400 Bad Request:

{
  "error": "'asset_model_uuid' is required"
}

• 404 Not Found:

{
  "error": "Asset model not found"
}

• 422 Unprocessable Entity:

{
  "error": "One or more payload UUIDs are not permitted by the specified asset model"
}

Bulk Create Assets

POST /assets/bulk

Register multiple assets simultaneously.

Request Body:

{
  "assets": [
    {
      "asset_uin": "UIN-IND-01239X",
      "uin_status": 1,
      "asset_org_internal_uuid": "ORG-DRN-001",
      "asset_model_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55",
      "org_owner_uuid": "9f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "source": 1,
      "active_payload_uuids": [
        "f8e9d0c1-b2a3-4455-6677-889900aabbcc"
      ]
    },
    {
      "asset_uin": null,
      "uin_status": 0,
      "asset_org_internal_uuid": "ORG-DRN-002",
      "asset_model_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55",
      "org_owner_uuid": "9f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "source": 1,
      "active_payload_uuids": []
    }
  ]
}

Responses:

• 201 Created:

{
  "message": "Bulk asset registration successful",
  "data": {
    "total_registered": 2,
    "assets": [
      ...
    ]
  }
}

• 400 Bad Request:

{
  "error": "'assets' array must not be empty"
}

• 422 Unprocessable Entity:

{
  "error": "One or more payload UUIDs in the batch are not permitted by the specified asset model"
}

Get Assets

GET /assets

Get all assets owned by organisation.

Query Parameters:

Responses:

• 200 OK:

{
  "data": [
    {
      "membership_uuid": "f3e0d7d8-5568-5c8b-93f5-221ce0a428b3",
      "membership_udai_id": "UDAI-MEM-0001",
      "status": 1,
      "created_at": "2024-12-20T10:00:00Z",
      "asset_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55",
      "asset_udai_id": "UDAI-AST-005",
      "asset_uin": "UIN-987654321",
      "uin_status": 1,
      "asset_status": 1,
      "total_distance": 15320,
      "total_endurance": 880,
      "total_flights": 78,
      "model_name": "Switch",
      "model_variant": "v2.Pro",
      "category": 2,
      "class": 3,
      "max_endurance": 3.5,
      "max_range": 15,
      "certificate_status": "Active"
    }
  ],
  "pagination": {
    "total_records": 78,
    "total_pages": 4,
    "current_page": 1,
    "per_page": 25,
    "has_next": true,
    "has_previous": false
  }
}

Get One Asset

GET /assets/{asset_uuid}

Get specific asset details.

Responses:

• 200 OK:

{
  "data": {
    "membership_uuid": "f3e0d7d8-5568-5c8b-93f5-221ce0a428b3",
    "membership_udai_id": "UDAI-MEM-0001",
    "status": 1,
    "created_at": "2024-12-20T10:00:00Z",
    "asset_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55",
    "asset_udai_id": "UDAI-AST-005",
    "asset_uin": "UIN-987654321",
    "uin_status": 1,
    "asset_status": 1,
    "total_distance": 15320,
    "total_endurance": 880,
    "total_flights": 78,
    "model_name": "Switch",
    "model_variant": "v2.Pro",
    "model_version": "v2.0",
    "type_certificate_number": "DGCA-CERT-99887",
    "manufacturer_uuid": "manufacturer-uuid-293",
    "category": 2,
    "sub_category": 2,
    "class": 3,
    "max_takeoff_weight": 12.5,
    "max_endurance": 3.5,
    "max_range": 15,
    "max_speed": 60,
    "max_height": 120,
    "operation_envelope": "VLOS",
    "frequency": "2.4GHz",
    "active_payload_uuids": [
      "f8e9d0c1-b2a3-4455-6677-889900aabbcc"
    ],
    "application": "Aerial Surveillance",
    "certificate_status": "Active"
  }
}

certificate_status is derived from the latest certificate record for the asset. Possible values are:

• 404 Not Found:

{
  "error": "Asset not found"
}

• 410 Gone:

{
  "error": "Asset has been deactivated"
}

Download Asset Certificate

GET /assets/{asset_uuid}/certificate

Generate or re-generate the X.509 certificate for an asset and download it as a .pfx file. This endpoint is used by the frontend when an asset owner downloads the certificate to install on the GCS machine.

Access: CanManageAssets policy. The asset must be actively owned by the requesting organisation.

Preconditions:

Response:

The downloaded filename follows the asset UDAI ID, for example UDAI-AST-005.pfx.

Important: Calling this endpoint when an active certificate already exists issues a fresh certificate and marks the previous active certificate as Superseded. The old PFX on the GCS machine stops working after the new certificate is generated, so the operator must replace it with the newly downloaded file.

Revoke Asset Certificate

POST /assets/{asset_uuid}/certificate/revoke

Revokes the currently active certificate for an asset. After revocation, the GCS utility is blocked on its next call to POST /certificates/validate.

Access: CanManageAssets policy (Admin+ within an Asset Owner organisation). The asset must be actively owned by the requesting organisation.

This endpoint takes no request body. The asset is identified by the path parameter.

Responses:

• 200 OK:

{
  "asset_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55",
  "certificate_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD",
  "revoked_at": "2026-06-16T10:15:00Z",
  "message": "Certificate has been revoked. The GCS utility will be blocked on its next validation attempt."
}

• 404 Not Found:

{
  "error": "Not found",
  "message": "No active certificate found for asset"
}

• 409 Conflict:

{
  "error": "Conflict",
  "message": "Certificate cannot be revoked in the current state"
}

Returned when revocation cannot proceed due to a conflicting certificate state.

• 401 Unauthorized / 403 Forbidden: Caller lacks CanManageAssets or does not own the asset.

Note: Revocation does not delete the certificate row. Status becomes Revoked. To restore GCS connectivity, download a new certificate via GET /assets/\{asset_uuid\}/certificate (which issues a fresh Active certificate and marks any previous Active cert as Superseded).

Validate Certificate

POST /certificates/validate

Validates that a presented certificate thumbprint is still Active for a given asset. Called by the UDAI Windows utility on startup before streaming telemetry.

Access: Anonymous: no bearer token or partner key is required. The certificate thumbprint itself is the credential.

Request Body:

{
  "thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD",
  "asset_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55"
}

Responses:

• 200 OK: certificate is Active, belongs to the asset, and has not expired:

{
  "valid": true
}

• 400 Bad Request: missing thumbprint or empty asset_uuid:

{
  "valid": false,
  "error": "Thumbprint and asset_uuid are required."
}

• 401 Unauthorized: not found, not Active (revoked/superseded), wrong asset, or expired:

{
  "valid": false,
  "error": "Certificate is not valid or has been revoked."
}

Other error values include "Certificate does not belong to the specified asset." and "Certificate has expired.".

Update Asset

PUT /assets/{asset_uuid}

Update specific details for a registered asset.

Request Body:

{
  "asset_uin": "UIN-987654321",
  "uin_status": 1,
  "asset_org_internal_uuid": "ORG-DRN-001-REV2",
  "active_payload_uuids": [
    "f8e9d0c1-b2a3-4455-6677-889900aabbcc"
  ],
  "status": 1
}

Responses:

• 200 OK:

{
  "message": "Asset updated successfully",
  "data": {
    ...
  }
}

• 400 Bad Request:

{
  "error": "'uin_status' must be 0 (Pending), 1 (Generated), or -1 (Failed)"
}

• 404 Not Found:

{
  "error": "Asset not found"
}

• 422 Unprocessable Entity:

{
  "error": "One or more payload UUIDs are not permitted by the asset model"
}

Delete Asset

DELETE /assets/{asset_uuid}

Remove the asset from the organisation records.

Responses:

• 200 OK:

{
  "message": "Status updated to REMOVED (-2)"
}

• 404 Not Found:

{
  "error": "Asset not found"
}

• 410 Gone:

{
  "error": "Asset is already inactive"
}

Asset Transitions & Memberships

The following routes are simplified shortcuts to the unified Resource Memberships API.

POST /assets/{asset_uuid}/transfers

Initiate an ownership transfer request to another organisation.

• Reference: POST /resource-invitations (with resource_type=2)

The destination organisation is supplied by its human-readable org_udai_id. The backend resolves this identifier to the organisation UUID used by the asset ownership record.

Request Body:

{
  "org_udai_id": "UDAI-ORG-0102",
  "remarks": "Transferring to regional fleet"
}

org_udai_id is the human-readable identifier for the destination organisation. The transfer remains organisation-owned; the backend resolves and stores the destination organisation UUID in the invitation and in the asset ownership record after acceptance.

The current owner’s X-Organisation-ID header is required when initiating the transfer. The response returns the resolved destination organisation UUID in data.invitee_uuid and the invitation UUID needed for acceptance.

GET /assets/{asset_uuid}/transfers

View all pending or past transfer requests for this asset.

• Reference: GET /resource-invitations?resource_type=2&resource_uuid=\{asset_uuid\}

POST /assets/{asset_uuid}/transfers/accept

Accept or decline a pending transfer for this asset.

• Reference: POST /resource-invitations/accept

Request Body:

{
  "invitation_uuid": "7b23c4d5-e6f7-8901-ab2c-3d4e5f6a7b8c",
  "accept": true
}

Acceptance uses the destination user’s bearer token and the destination organisation’s X-Organisation-ID. The header identifies the organisation the accepting user is acting for; the invitation still determines the transfer target.

DELETE /assets/{asset_uuid}/membership

Revoke the current active ownership membership for this asset.

• Reference: DELETE /resource-memberships/\{membership_uuid\}