Payload Model API

Access: org_type = Asset Manufacturer or Asset Owner. Admin+ for create/update/delete. Member+ for reads. See access-control.md.

Payload models are owned by a single organisation (org_owner_uuid, set to the active org on creation). Every endpoint here is scoped to the caller’s organisation. To read the payloads a drone model supports without owning them (for example after receiving an asset via transfer), use GET /asset-models/\{model_uuid\}/payloads.

Payload Model Endpoints Summary

Endpoint	Method	Operation Name	Description
`/payload-models`	POST	Create Payload Model	Register a physical payload model
`/payload-models`	GET	Get Payload Models	Get all payload models owned by organisation
`/payload-models/\{payload_uuid\}`	GET	Get One Payload Model	Get specific payload model details
`/payload-models/\{payload_uuid\}`	PUT	Update Payload Model	Update specific payload model details
`/payload-models/\{payload_uuid\}`	DELETE	Delete Payload Model	Remove the payload model (soft-delete to INACTIVE)

Create Payload Model

POST /payload-models

Request Body:


{
  "payload_name": "Ninja Thermal H1",
  "payload_type": 2,
  "manufacturer": "Ideaforge",
  "weight_kg": 0.85,
  "horizontal_swath": 120.5,
  "vertical_swath": 90.2
}

Field	Type	Description
`payload_name`	string	Name or model of the payload
`payload_type`	int	Enum value for the payload type (e.g., 2 = Thermal Camera)
`manufacturer`	string	Name of the manufacturer
`weight_kg`	double	Weight in kilograms
`horizontal_swath`	double	Horizontal swath width (metres)
`vertical_swath`	double	Vertical swath width (metres)

Responses:

201 Created:


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

400 Bad Request:


{
  "error": "'payload_type' must be a valid payload type enum"
}

422 Unprocessable Entity:


{
  "error": "'weight_kg' must be a positive number"
}

Get Payload Models

GET /payload-models

Get all payload models owned by the organisation.

Query Parameters:

Param	Type	Description
`page`	int (optional)	Page number (default: 1)
`limit`	int (optional)	Records per page (default: 25)

Responses:

200 OK:


{
  "data": [
    {
      "payload_uuid": "f8e9d0c1-b2a3-4455-6677-889900aabbcc",
      "payload_udai_id": "UDAI-PAY-045",
      "payload_name": "Ninja Thermal H1",
      "payload_type": 2,
      "manufacturer": "Ideaforge",
      "org_owner_uuid": "9f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "weight_kg": 0.85,
      "horizontal_swath": 120.5,
      "vertical_swath": 90.2,
      "status": 1
    }
  ],
  "pagination": {
    "total_records": 10,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 25,
    "has_next": false,
    "has_previous": false
  }
}

Get One Payload Model

GET /payload-models/{payload_uuid}

Get specific payload details.

Responses:

200 OK:


{
  "data": {
    "payload_uuid": "f8e9d0c1-b2a3-4455-6677-889900aabbcc",
    "payload_udai_id": "UDAI-PAY-045",
    "payload_name": "Ninja Thermal H1",
    "payload_type": 2,
    "manufacturer": "Ideaforge",
    "weight_kg": 0.85,
    "horizontal_swath": 120.5,
    "vertical_swath": 90.2,
    "status": 1,
    "created_at": "2025-07-04T10:00:00Z",
    "updated_at": "2025-07-04T10:00:00Z"
  }
}

404 Not Found:


{
  "error": "Payload not found"
}

410 Gone:


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

Update Payload Model

PUT /payload-models/{payload_uuid}

Update specific details for a registered payload model.

Request Body:


{
  "payload_name": "Ninja Thermal H1 - Updated",
  "status": 1
}

Field	Type	Description
`payload_name`	string (optional)	Updated name or model of the payload
`status`	int (optional)	1 for Active, -1 for Inactive

Responses:

200 OK:


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

400 Bad Request:


{
  "error": "'status' must be 1 (Active) or -1 (Inactive)"
}

404 Not Found:


{
  "error": "Payload not found"
}

422 Unprocessable Entity:


{
  "error": "'weight_kg' must be a positive number"
}

Delete Payload Model

DELETE /payload-models/{payload_uuid}

Remove the payload model from the organisation’s active records.

Responses:

200 OK:


{
  "message": "Status updated to INACTIVE"
}

404 Not Found:


{
  "error": "Payload not found"
}

410 Gone:


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