Jump to main content
Expand
Model Service Admin

Model Service Admin

read_brand

Introduced in version 21

Summary: GET /v1/brand/<brand_account_id>

Read a brand entity in snapmodels.

URL Parameters

{
    "properties": {
        "fields": {
            "description": "A comma-separated list of fields to retrieve. Available fields: account-id, created-at, created-by, modified-at, modified-by, name.",
            "type": "string"
        }
    },
    "type": "object"
}

  • fields

    • description: A comma-separated list of fields to retrieve. Available fields: account-id, created-at, created-by, modified-at, modified-by, name.

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "account-id": {
            "type": "string"
        },
        "created-at": {
            "type": "string"
        },
        "created-by": {
            "additionalProperties": false,
            "properties": {
                "display-name": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "email": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "username": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "validation": {
                    "type": "string"
                }
            },
            "required": [
                "display-name",
                "id",
                "username"
            ],
            "type": "object"
        },
        "modified-at": {
            "type": [
                "string",
                "null"
            ]
        },
        "modified-by": {
            "oneOf": [
                {
                    "additionalProperties": false,
                    "properties": {
                        "display-name": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        },
                        "email": {
                            "type": "string"
                        },
                        "id": {
                            "type": "string"
                        },
                        "username": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        },
                        "validation": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "display-name",
                        "id",
                        "username"
                    ],
                    "type": "object"
                },
                {
                    "type": "null"
                }
            ]
        },
        "name": {
            "type": "string"
        }
    },
    "type": "object"
}

update_brand

Introduced in version 21

Summary: PATCH /v1/brand/<brand_account_id>

Update a brand entity in snapmodels.

Request JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "name": {
            "type": "string"
        }
    },
    "type": "object"
}

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "account-id": {
            "type": "string"
        },
        "created-at": {
            "type": "string"
        },
        "created-by": {
            "additionalProperties": false,
            "properties": {
                "display-name": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "email": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "username": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "validation": {
                    "type": "string"
                }
            },
            "required": [
                "display-name",
                "id",
                "username"
            ],
            "type": "object"
        },
        "modified-at": {
            "type": [
                "string",
                "null"
            ]
        },
        "modified-by": {
            "oneOf": [
                {
                    "additionalProperties": false,
                    "properties": {
                        "display-name": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        },
                        "email": {
                            "type": "string"
                        },
                        "id": {
                            "type": "string"
                        },
                        "username": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        },
                        "validation": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "display-name",
                        "id",
                        "username"
                    ],
                    "type": "object"
                },
                {
                    "type": "null"
                }
            ]
        },
        "name": {
            "type": "string"
        }
    },
    "required": [
        "account-id",
        "name",
        "created-by",
        "created-at",
        "modified-by",
        "modified-at"
    ],
    "type": "object"
}

delete_brand

Introduced in version 21

Summary: DELETE /v1/brand/<brand_account_id>

Delete a brand entity in snapmodels.

create_model

Introduced in version 22

Summary: POST /v1/brand/<brand_account_id>/model

Create a model under a brand in snapmodels.

Request JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "api-key": {
            "type": "string"
        },
        "name": {
            "type": "string"
        },
        "series": {
            "type": "string"
        }
    },
    "required": [
        "name",
        "series"
    ],
    "type": "object"
}

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "api-key": {
            "type": [
                "string",
                "null"
            ]
        },
        "brand-account-id": {
            "type": "string"
        },
        "created-at": {
            "type": "string"
        },
        "created-by": {
            "additionalProperties": false,
            "properties": {
                "display-name": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "email": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "username": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "validation": {
                    "type": "string"
                }
            },
            "required": [
                "display-name",
                "id",
                "username"
            ],
            "type": "object"
        },
        "modified-at": {
            "type": [
                "string",
                "null"
            ]
        },
        "modified-by": {
            "oneOf": [
                {
                    "additionalProperties": false,
                    "properties": {
                        "display-name": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        },
                        "email": {
                            "type": "string"
                        },
                        "id": {
                            "type": "string"
                        },
                        "username": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        },
                        "validation": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "display-name",
                        "id",
                        "username"
                    ],
                    "type": "object"
                },
                {
                    "type": "null"
                }
            ]
        },
        "name": {
            "type": "string"
        },
        "series": {
            "type": "string"
        }
    },
    "required": [
        "brand-account-id",
        "name",
        "series",
        "api-key",
        "created-by",
        "created-at",
        "modified-by",
        "modified-at"
    ],
    "type": "object"
}

read_models

Introduced in version 22

Summary: GET /v1/brand/<brand_account_id>/model

Read the list of models owned by a brand in snapmodels.

The fields query parameter can be used to specify attributes to fetch. If empty, then all attributes are fetched.

URL Parameters

{
    "properties": {
        "fields": {
            "description": "A comma-separated list of fields to retrieve. Available fields: api-key, brand-account-id, created-at, created-by, modified-at, modified-by, name, series.",
            "type": "string"
        }
    },
    "type": "object"
}

  • fields

    • description: A comma-separated list of fields to retrieve. Available fields: api-key, brand-account-id, created-at, created-by, modified-at, modified-by, name, series.

Response JSON Schema

{
    "items": {
        "additionalProperties": false,
        "properties": {
            "api-key": {
                "type": [
                    "string",
                    "null"
                ]
            },
            "brand-account-id": {
                "type": "string"
            },
            "created-at": {
                "type": "string"
            },
            "created-by": {
                "additionalProperties": false,
                "properties": {
                    "display-name": {
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "email": {
                        "type": "string"
                    },
                    "id": {
                        "type": "string"
                    },
                    "username": {
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "validation": {
                        "type": "string"
                    }
                },
                "required": [
                    "display-name",
                    "id",
                    "username"
                ],
                "type": "object"
            },
            "modified-at": {
                "type": [
                    "string",
                    "null"
                ]
            },
            "modified-by": {
                "oneOf": [
                    {
                        "additionalProperties": false,
                        "properties": {
                            "display-name": {
                                "oneOf": [
                                    {
                                        "type": "string"
                                    },
                                    {
                                        "type": "null"
                                    }
                                ]
                            },
                            "email": {
                                "type": "string"
                            },
                            "id": {
                                "type": "string"
                            },
                            "username": {
                                "oneOf": [
                                    {
                                        "type": "string"
                                    },
                                    {
                                        "type": "null"
                                    }
                                ]
                            },
                            "validation": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "display-name",
                            "id",
                            "username"
                        ],
                        "type": "object"
                    },
                    {
                        "type": "null"
                    }
                ]
            },
            "name": {
                "type": "string"
            },
            "series": {
                "type": "string"
            }
        },
        "type": "object"
    },
    "type": "array"
}

update_model

Introduced in version 22

Summary: PATCH /v1/brand/<brand_account_id>/model/<model_name>

Update a model in snapmodels. Only series and api_key can be updated.

Request JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "api-key": {
            "type": "string"
        },
        "series": {
            "type": "string"
        }
    },
    "type": "object"
}

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "api-key": {
            "type": [
                "string",
                "null"
            ]
        },
        "brand-account-id": {
            "type": "string"
        },
        "created-at": {
            "type": "string"
        },
        "created-by": {
            "additionalProperties": false,
            "properties": {
                "display-name": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "email": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "username": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "validation": {
                    "type": "string"
                }
            },
            "required": [
                "display-name",
                "id",
                "username"
            ],
            "type": "object"
        },
        "modified-at": {
            "type": [
                "string",
                "null"
            ]
        },
        "modified-by": {
            "oneOf": [
                {
                    "additionalProperties": false,
                    "properties": {
                        "display-name": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        },
                        "email": {
                            "type": "string"
                        },
                        "id": {
                            "type": "string"
                        },
                        "username": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        },
                        "validation": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "display-name",
                        "id",
                        "username"
                    ],
                    "type": "object"
                },
                {
                    "type": "null"
                }
            ]
        },
        "name": {
            "type": "string"
        },
        "series": {
            "type": "string"
        }
    },
    "required": [
        "brand-account-id",
        "name",
        "series",
        "api-key",
        "created-by",
        "created-at",
        "modified-by",
        "modified-at"
    ],
    "type": "object"
}

delete_model

Introduced in version 22

Summary: DELETE /v1/brand/<brand_account_id>/model/<model_name>

Delete a model in snapmodels.

create_signing_key

Introduced in version 23

Summary: POST /v1/brand/<brand_account_id>/signing_key

Create a signing key for a brand in snapmodels.

Request JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "name": {
            "type": "string"
        }
    },
    "required": [
        "name"
    ],
    "type": "object"
}

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "brand-account-id": {
            "type": "string"
        },
        "created-at": {
            "type": "string"
        },
        "created-by": {
            "additionalProperties": false,
            "properties": {
                "display-name": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "email": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "username": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "validation": {
                    "type": "string"
                }
            },
            "required": [
                "display-name",
                "id",
                "username"
            ],
            "type": "object"
        },
        "fingerprint": {
            "type": "string"
        },
        "modified-at": {
            "type": [
                "string",
                "null"
            ]
        },
        "modified-by": {
            "oneOf": [
                {
                    "additionalProperties": false,
                    "properties": {
                        "display-name": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        },
                        "email": {
                            "type": "string"
                        },
                        "id": {
                            "type": "string"
                        },
                        "username": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        },
                        "validation": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "display-name",
                        "id",
                        "username"
                    ],
                    "type": "object"
                },
                {
                    "type": "null"
                }
            ]
        },
        "name": {
            "type": "string"
        },
        "sha3-384": {
            "type": "string"
        }
    },
    "required": [
        "brand-account-id",
        "name",
        "fingerprint",
        "sha3-384",
        "created-by",
        "created-at",
        "modified-by",
        "modified-at"
    ],
    "type": "object"
}

read_signing_keys

Introduced in version 23

Summary: GET /v1/brand/<brand_account_id>/signing_key

Read the list of signing keys that can be used for a brand in snapmodels.

The fields query parameter can be used to specify attributes to fetch. If empty, then all attributes are fetched.

URL Parameters

{
    "properties": {
        "fields": {
            "description": "A comma-separated list of fields to retrieve. Available fields: brand-account-id, created-at, created-by, fingerprint, modified-at, modified-by, name, sha3-384.",
            "type": "string"
        }
    },
    "type": "object"
}

  • fields

    • description: A comma-separated list of fields to retrieve. Available fields: brand-account-id, created-at, created-by, fingerprint, modified-at, modified-by, name, sha3-384.

Response JSON Schema

{
    "items": {
        "additionalProperties": false,
        "properties": {
            "brand-account-id": {
                "type": "string"
            },
            "created-at": {
                "type": "string"
            },
            "created-by": {
                "additionalProperties": false,
                "properties": {
                    "display-name": {
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "email": {
                        "type": "string"
                    },
                    "id": {
                        "type": "string"
                    },
                    "username": {
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "validation": {
                        "type": "string"
                    }
                },
                "required": [
                    "display-name",
                    "id",
                    "username"
                ],
                "type": "object"
            },
            "fingerprint": {
                "type": "string"
            },
            "modified-at": {
                "type": [
                    "string",
                    "null"
                ]
            },
            "modified-by": {
                "oneOf": [
                    {
                        "additionalProperties": false,
                        "properties": {
                            "display-name": {
                                "oneOf": [
                                    {
                                        "type": "string"
                                    },
                                    {
                                        "type": "null"
                                    }
                                ]
                            },
                            "email": {
                                "type": "string"
                            },
                            "id": {
                                "type": "string"
                            },
                            "username": {
                                "oneOf": [
                                    {
                                        "type": "string"
                                    },
                                    {
                                        "type": "null"
                                    }
                                ]
                            },
                            "validation": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "display-name",
                            "id",
                            "username"
                        ],
                        "type": "object"
                    },
                    {
                        "type": "null"
                    }
                ]
            },
            "name": {
                "type": "string"
            },
            "sha3-384": {
                "type": "string"
            }
        },
        "type": "object"
    },
    "type": "array"
}

read_signing_key_account_key_request

Introduced in version 26

Summary: POST /v1/brand/<brand_account_id>/signing_key/<signing_key_sha3_384>/account-key-request

Get an account-key-request for the given signing key.

In on-prem/offline scenarios, we are unable to create an account-key with SAS using the Canonical root key. So we allow an admin to get an account-key-request assertion that can be registered in an online environment. The new account-key assertion can then be pushed to SAS on the proxy host, allowing things like serial signing to work as expected. This approach is preferred as it allows for remote administration of the proxy, without needing access to the HSM on the proxy host.

update_signing_key

Introduced in version 23

Summary: PATCH /v1/brand/<brand_account_id>/signing_key/<signing_key_sha3_384>

Update a signing key in snapmodels. Only its descriptive name can be updated.

Request JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "name": {
            "type": "string"
        }
    },
    "type": "object"
}

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "brand-account-id": {
            "type": "string"
        },
        "created-at": {
            "type": "string"
        },
        "created-by": {
            "additionalProperties": false,
            "properties": {
                "display-name": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "email": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "username": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "validation": {
                    "type": "string"
                }
            },
            "required": [
                "display-name",
                "id",
                "username"
            ],
            "type": "object"
        },
        "fingerprint": {
            "type": "string"
        },
        "modified-at": {
            "type": [
                "string",
                "null"
            ]
        },
        "modified-by": {
            "oneOf": [
                {
                    "additionalProperties": false,
                    "properties": {
                        "display-name": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        },
                        "email": {
                            "type": "string"
                        },
                        "id": {
                            "type": "string"
                        },
                        "username": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        },
                        "validation": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "display-name",
                        "id",
                        "username"
                    ],
                    "type": "object"
                },
                {
                    "type": "null"
                }
            ]
        },
        "name": {
            "type": "string"
        },
        "sha3-384": {
            "type": "string"
        }
    },
    "required": [
        "brand-account-id",
        "name",
        "fingerprint",
        "sha3-384",
        "created-by",
        "created-at",
        "modified-by",
        "modified-at"
    ],
    "type": "object"
}

delete_signing_key

Introduced in version 23

Summary: DELETE /v1/brand/<brand_account_id>/signing_key/<signing_key_sha3_384>

Delete a signing_key in snapmodels. Key revocation in snapassert handled by snapmodels.

create_hardware_identities

Introduced in version 54

Summary: POST /v1/brand/<brand_account_id>/hardware-identity

Create one or more hardware identities and associate them with a specific brand.

This endpoint expects multipart/form-data with one or more files under the field name files.

Example:

curl -XPOST "https://example.com/v1/brand/<brand_account_id>/hardware-identity" \
-F "files=@file1.assert" \
-F "files=@file2.assert" \
-H "Authorization: macaroon <MACAROON>"

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "new-inserts-count": {
            "type": "integer"
        }
    },
    "required": [
        "new-inserts-count"
    ],
    "type": "object"
}

read_hardware_identities

Introduced in version 54

Summary: GET /v1/brand/<brand_account_id>/hardware-identity

Returns a cursor-paginated list of hardware identities for the given brand.

Results are sorted by creation timestamp (descending), and for items with the same creation timestamp, by hardware-id-key-sha3-384 (descending).

URL Parameters

{
    "additionalProperties": false,
    "properties": {
        "cursor": {
            "description": "Cursor for pagination",
            "type": "string"
        },
        "include-assertion": {
            "enum": [
                "true",
                "false"
            ],
            "type": "string"
        },
        "include-key": {
            "enum": [
                "true",
                "false"
            ],
            "type": "string"
        },
        "page-size": {
            "description": "Number of items per page (1-500). Defaults to 100.",
            "pattern": "^[1-9][0-9]*$",
            "type": "string"
        }
    },
    "type": "object"
}

  • cursor

    • description: Cursor for pagination

  • include-assertion

    • Must be one of “true” or “false”

  • include-key

    • Must be one of “true” or “false”

  • page-size

    • description: Number of items per page (1-500). Defaults to 100.

    • Must match regex “^[1-9][0-9]*$”

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "items": {
            "items": {
                "properties": {
                    "assertion": {
                        "type": "string"
                    },
                    "hardware-id": {
                        "type": "string"
                    },
                    "hardware-id-key": {
                        "type": "string"
                    },
                    "hardware-id-key-sha3-384": {
                        "type": "string"
                    },
                    "hardware-name": {
                        "type": "string"
                    },
                    "issuer-id": {
                        "type": "string"
                    },
                    "manufacturer": {
                        "type": "string"
                    },
                    "sign-key-sha3-384": {
                        "type": "string"
                    }
                },
                "required": [
                    "issuer-id",
                    "manufacturer",
                    "hardware-name",
                    "hardware-id",
                    "hardware-id-key-sha3-384",
                    "sign-key-sha3-384"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "next-cursor": {
            "oneOf": [
                {
                    "type": "null"
                },
                {
                    "type": "string"
                }
            ]
        }
    },
    "required": [
        "items",
        "next-cursor"
    ],
    "type": "object"
}

read_hardware_identity

Introduced in version 54

Summary: GET /v1/brand/<brand_account_id>/hardware-identity/<hardware_id_key_sha3_384>

Read a specific hardware identity associated with a given brand.

URL Parameters

{
    "additionalProperties": false,
    "properties": {
        "include-assertion": {
            "enum": [
                "true",
                "false"
            ],
            "type": "string"
        },
        "include-key": {
            "enum": [
                "true",
                "false"
            ],
            "type": "string"
        }
    },
    "type": "object"
}

  • include-assertion

    • Must be one of “true” or “false”

  • include-key

    • Must be one of “true” or “false”

Response JSON Schema

{
    "properties": {
        "assertion": {
            "type": "string"
        },
        "hardware-id": {
            "type": "string"
        },
        "hardware-id-key": {
            "type": "string"
        },
        "hardware-id-key-sha3-384": {
            "type": "string"
        },
        "hardware-name": {
            "type": "string"
        },
        "issuer-id": {
            "type": "string"
        },
        "manufacturer": {
            "type": "string"
        },
        "sign-key-sha3-384": {
            "type": "string"
        }
    },
    "required": [
        "issuer-id",
        "manufacturer",
        "hardware-name",
        "hardware-id",
        "hardware-id-key-sha3-384",
        "sign-key-sha3-384"
    ],
    "type": "object"
}

delete_hardware_identity

Introduced in version 54

Summary: DELETE /v1/brand/<brand_account_id>/hardware-identity/<hardware_id_key_sha3_384>

Delete a hardware identity.

Response JSON Schema

{
    "additionalProperties": false,
    "type": "object"
}

create_serial_policy

Introduced in version 24

Summary: POST /v1/brand/<brand_account_id>/model/<model_name>/serial_policy

Create a serial policy for a model in snapmodels.

create_serial_policy changelog

  • Version 63: Introduce provisioning-auth

Request JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "provisioning-auth": {
            "enum": [
                "api-key",
                "hardware-identity"
            ],
            "introduced_at": 63
        },
        "signing-key-sha3-384": {
            "type": "string"
        }
    },
    "required": [
        "signing-key-sha3-384"
    ],
    "type": "object"
}

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "authority": {
            "type": "string"
        },
        "created-at": {
            "type": "string"
        },
        "created-by": {
            "additionalProperties": false,
            "properties": {
                "display-name": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "email": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "username": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "validation": {
                    "type": "string"
                }
            },
            "required": [
                "display-name",
                "id",
                "username"
            ],
            "type": "object"
        },
        "model-name": {
            "type": "string"
        },
        "provisioning-auth": {
            "enum": [
                "api-key",
                "hardware-identity"
            ],
            "introduced_at": 63
        },
        "revision": {
            "type": "integer"
        },
        "signing-key-sha3-384": {
            "type": "string"
        }
    },
    "required": [
        "model-name",
        "revision",
        "signing-key-sha3-384",
        "authority",
        "provisioning-auth",
        "created-by",
        "created-at"
    ],
    "type": "object"
}

read_serial_policies

Introduced in version 24

Summary: GET /v1/brand/<brand_account_id>/model/<model_name>/serial_policy

Read the list of serial policies associated with a model in snapmodels.

The fields query parameter can be used to specify attributes to fetch. If empty, then all attributes are fetched.

read_serial_policies changelog

  • Version 63: Introduce provisioning-auth in response body

URL Parameters

{
    "properties": {
        "fields": {
            "description": "A comma-separated list of fields to retrieve. Available fields: authority, created-at, created-by, model-name, provisioning-auth, revision, signing-key-sha3-384.",
            "type": "string"
        }
    },
    "type": "object"
}

  • fields

    • description: A comma-separated list of fields to retrieve. Available fields: authority, created-at, created-by, model-name, provisioning-auth, revision, signing-key-sha3-384.

Response JSON Schema

{
    "items": {
        "additionalProperties": false,
        "properties": {
            "authority": {
                "type": "string"
            },
            "created-at": {
                "type": "string"
            },
            "created-by": {
                "additionalProperties": false,
                "properties": {
                    "display-name": {
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "email": {
                        "type": "string"
                    },
                    "id": {
                        "type": "string"
                    },
                    "username": {
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "validation": {
                        "type": "string"
                    }
                },
                "required": [
                    "display-name",
                    "id",
                    "username"
                ],
                "type": "object"
            },
            "model-name": {
                "type": "string"
            },
            "provisioning-auth": {
                "enum": [
                    "api-key",
                    "hardware-identity"
                ],
                "introduced_at": 63
            },
            "revision": {
                "type": "integer"
            },
            "signing-key-sha3-384": {
                "type": "string"
            }
        },
        "type": "object"
    },
    "type": "array"
}

delete_serial_policy

Introduced in version 24

Summary: DELETE /v1/brand/<brand_account_id>/model/<model_name>/serial_policy/<serial_policy_rev>

Delete a model’s serial policy in snapmodels.

create_remodel_allowlist

Introduced in version 56

Summary: POST /v1/brand/<brand_account_id>/remodel-allowlist

Allow remodeling for the given device(s) to the target model(s).

Devices are identified by the brand/model/serial, with the brand specified in the URL path and the model/serial in the payload.

Duplicate allowlists are not allowed.

The response contains the created allowlist.

Request JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "allowlist": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "description": {
                        "type": "string"
                    },
                    "from-model": {
                        "minLength": 1,
                        "type": "string"
                    },
                    "from-serial": {
                        "oneOf": [
                            {
                                "type": "null"
                            },
                            {
                                "minLength": 1,
                                "type": "string"
                            }
                        ]
                    },
                    "to-model": {
                        "minLength": 1,
                        "type": "string"
                    }
                },
                "required": [
                    "from-model",
                    "from-serial",
                    "to-model"
                ],
                "type": "object"
            },
            "minItems": 1,
            "type": "array"
        }
    },
    "required": [
        "allowlist"
    ],
    "type": "object"
}

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "allowlist": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "created-at": {
                        "type": "string"
                    },
                    "created-by": {
                        "type": "string"
                    },
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "from-model": {
                        "type": "string"
                    },
                    "from-serial": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "modified-at": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "modified-by": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "to-model": {
                        "type": "string"
                    }
                },
                "required": [
                    "from-model",
                    "from-serial",
                    "to-model",
                    "description",
                    "created-at",
                    "created-by",
                    "modified-at",
                    "modified-by"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "allowlist"
    ],
    "type": "object"
}

read_serial_logs_by_time

Introduced in version 63

Summary: GET /v1/brand/<brand_account_id>/model/<model_name>/serial-log

Read the list of serial logs of a brand model in snapmodels by time.

Default to read serial logs in last 30 days from latest to oldest.

URL Parameters

{
    "additionalProperties": false,
    "properties": {
        "cursor": {
            "description": "Cursor for pagination",
            "type": "string"
        },
        "end-time": {
            "description": "Default to last 30 days.",
            "format": "date-time",
            "type": "string"
        },
        "page-size": {
            "description": "Number of items per page (1-500). Defaults to 100.",
            "pattern": "^[1-9][0-9]*$",
            "type": "string"
        },
        "start-time": {
            "description": "Default to last 30 days.",
            "format": "date-time",
            "type": "string"
        }
    },
    "type": "object"
}

  • cursor

    • description: Cursor for pagination

  • end-time

    • description: Default to last 30 days.

  • page-size

    • description: Number of items per page (1-500). Defaults to 100.

    • Must match regex “^[1-9][0-9]*$”

  • start-time

    • description: Default to last 30 days.

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "items": {
            "items": {
                "properties": {
                    "brand-id": {
                        "type": "string"
                    },
                    "created-at": {
                        "format": "date-time",
                        "type": "string"
                    },
                    "model-name": {
                        "type": "string"
                    },
                    "serial": {
                        "type": "string"
                    },
                    "serial-assertion": {
                        "type": "string"
                    },
                    "serial-request-assertion": {
                        "type": "string"
                    },
                    "serial-sign-key-sha3-384": {
                        "type": "string"
                    }
                },
                "required": [
                    "brand-id",
                    "model-name",
                    "serial",
                    "created-at"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "next-cursor": {
            "oneOf": [
                {
                    "type": "null"
                },
                {
                    "type": "string"
                }
            ]
        }
    },
    "required": [
        "items",
        "next-cursor"
    ],
    "type": "object"
}

read_serial_logs_by_serial

Introduced in version 63

Summary: GET /v1/brand/<brand_account_id>/model/<model_name>/serial/<serial>/serial-log

Read the list of serial logs of a brand model in snapmodels by serial.

Optional filters: include-serial-assertion, include-serial-request-assertion. Assertions are not fetched by default; opt in explicitly to include them.

URL Parameters

{
    "additionalProperties": false,
    "properties": {
        "include-serial-assertion": {
            "enum": [
                "true",
                "false"
            ],
            "type": "string"
        },
        "include-serial-request-assertion": {
            "enum": [
                "true",
                "false"
            ],
            "type": "string"
        }
    },
    "type": "object"
}

  • include-serial-assertion

    • Must be one of “true” or “false”

  • include-serial-request-assertion

    • Must be one of “true” or “false”

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "items": {
            "items": {
                "properties": {
                    "brand-id": {
                        "type": "string"
                    },
                    "created-at": {
                        "format": "date-time",
                        "type": "string"
                    },
                    "model-name": {
                        "type": "string"
                    },
                    "serial": {
                        "type": "string"
                    },
                    "serial-assertion": {
                        "type": "string"
                    },
                    "serial-request-assertion": {
                        "type": "string"
                    },
                    "serial-sign-key-sha3-384": {
                        "type": "string"
                    }
                },
                "required": [
                    "brand-id",
                    "model-name",
                    "serial",
                    "created-at"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "items"
    ],
    "type": "object"
}

read_serial_logs

Introduced in version 58

Summary: GET /v1/brand/<brand_account_id>/serial-log

Read the list of serial logs in snapmodel for offline store. Use read_serial_logs_by_time, read_serial_logs_by_serial instead for online SaaS store.

Optional filters: model-name, serial, (start-time, end-time), include-serial-assertion, include-serial-request-assertion.

Assertions are not fetched by default; opt in explicitly to include them.

URL Parameters

{
    "additionalProperties": false,
    "properties": {
        "cursor": {
            "description": "Cursor for pagination",
            "type": "string"
        },
        "end-time": {
            "format": "date-time",
            "type": "string"
        },
        "include-serial-assertion": {
            "enum": [
                "true",
                "false"
            ],
            "type": "string"
        },
        "include-serial-request-assertion": {
            "enum": [
                "true",
                "false"
            ],
            "type": "string"
        },
        "model-name": {
            "type": "string"
        },
        "page-size": {
            "description": "Number of items per page (1-500). Defaults to 100.",
            "pattern": "^[1-9][0-9]*$",
            "type": "string"
        },
        "serial": {
            "type": "string"
        },
        "start-time": {
            "format": "date-time",
            "type": "string"
        }
    },
    "type": "object"
}

  • cursor

    • description: Cursor for pagination

  • end-time

  • include-serial-assertion

    • Must be one of “true” or “false”

  • include-serial-request-assertion

    • Must be one of “true” or “false”

  • model-name

  • page-size

    • description: Number of items per page (1-500). Defaults to 100.

    • Must match regex “^[1-9][0-9]*$”

  • serial

  • start-time

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "items": {
            "items": {
                "properties": {
                    "brand-id": {
                        "type": "string"
                    },
                    "created-at": {
                        "format": "date-time",
                        "type": "string"
                    },
                    "model-name": {
                        "type": "string"
                    },
                    "serial": {
                        "type": "string"
                    },
                    "serial-assertion": {
                        "type": "string"
                    },
                    "serial-request-assertion": {
                        "type": "string"
                    },
                    "serial-sign-key-sha3-384": {
                        "type": "string"
                    }
                },
                "required": [
                    "brand-id",
                    "model-name",
                    "serial",
                    "created-at"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "next-cursor": {
            "oneOf": [
                {
                    "type": "null"
                },
                {
                    "type": "string"
                }
            ]
        }
    },
    "required": [
        "items",
        "next-cursor"
    ],
    "type": "object"
}

read_remodel_allowlist

Introduced in version 59

Summary: GET /v1/brand/<brand_account_id>/remodel-allowlist

Get the remodel allowlist for the given brand.

This API is cursor-paginated. A null value for the returned next-cursor indicates that there are no more pages to be fetched. If the next-cursor value is not null, then there is at least one more page to be fetched. The next page can be fetched with another API call, where cursor is set to the value in next-cursor.

Results are returned in ascending order, based on the (from-model, to-model, from-serial) tuple.

The page-size query param may be used to indicate the desired page size. The default page size is 100, with a maximum value of 500.

The from-model query param may be used to only include from-models with the matching value.

In the response, a null value for the from-serial field indicates a wildcard. This means that the remodel permission allows for any device to remodel from the given initial model to the target model.

URL Parameters

{
    "additionalProperties": false,
    "properties": {
        "cursor": {
            "description": "Cursor for pagination",
            "type": "string"
        },
        "from-model": {
            "minLength": 1,
            "type": "string"
        },
        "page-size": {
            "description": "Number of items per page (1-500). Defaults to 100.",
            "pattern": "^[1-9][0-9]*$",
            "type": "string"
        }
    },
    "type": "object"
}

  • cursor

    • description: Cursor for pagination

  • from-model

    • Length must be >= 1

  • page-size

    • description: Number of items per page (1-500). Defaults to 100.

    • Must match regex “^[1-9][0-9]*$”

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "allowlist": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "created-at": {
                        "type": "string"
                    },
                    "created-by": {
                        "type": "string"
                    },
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "from-model": {
                        "type": "string"
                    },
                    "from-serial": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "modified-at": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "modified-by": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "to-model": {
                        "type": "string"
                    }
                },
                "required": [
                    "from-model",
                    "from-serial",
                    "to-model",
                    "description",
                    "created-at",
                    "created-by",
                    "modified-at",
                    "modified-by"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "next-cursor": {
            "type": [
                "string",
                "null"
            ]
        }
    },
    "required": [
        "allowlist",
        "next-cursor"
    ],
    "type": "object"
}

delete_remodel_allowlist

Introduced in version 60

Summary: POST /v1/brand/<brand_account_id>/remodel-allowlist/delete

Delete the allowed remodel permission(s) for the given brand.

null may be used for from-serial to indicate deletion of the wildcard entry.

Request JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "allowlist": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "from-model": {
                        "minLength": 1,
                        "type": "string"
                    },
                    "from-serial": {
                        "oneOf": [
                            {
                                "type": "null"
                            },
                            {
                                "minLength": 1,
                                "type": "string"
                            }
                        ]
                    },
                    "to-model": {
                        "minLength": 1,
                        "type": "string"
                    }
                },
                "required": [
                    "from-model",
                    "from-serial",
                    "to-model"
                ],
                "type": "object"
            },
            "minItems": 1,
            "type": "array"
        }
    },
    "required": [
        "allowlist"
    ],
    "type": "object"
}

Response JSON Schema

{
    "additionalProperties": false,
    "type": "object"
}

update_remodel_allowlist

Introduced in version 61

Summary: PATCH /v1/brand/<brand_account_id>/remodel-allowlist

Update the allowed remodel permission(s) for the given brand.

Only the description may be updated currently.

null may be used for from-serial to update the given wildcard entry.

The response contains the updated allowlist.

Request JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "allowlist": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "from-model": {
                        "minLength": 1,
                        "type": "string"
                    },
                    "from-serial": {
                        "oneOf": [
                            {
                                "type": "null"
                            },
                            {
                                "minLength": 1,
                                "type": "string"
                            }
                        ]
                    },
                    "to-model": {
                        "minLength": 1,
                        "type": "string"
                    }
                },
                "required": [
                    "from-model",
                    "from-serial",
                    "to-model",
                    "description"
                ],
                "type": "object"
            },
            "minItems": 1,
            "type": "array"
        }
    },
    "required": [
        "allowlist"
    ],
    "type": "object"
}

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "allowlist": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "created-at": {
                        "type": "string"
                    },
                    "created-by": {
                        "type": "string"
                    },
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "from-model": {
                        "type": "string"
                    },
                    "from-serial": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "modified-at": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "modified-by": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "to-model": {
                        "type": "string"
                    }
                },
                "required": [
                    "from-model",
                    "from-serial",
                    "to-model",
                    "description",
                    "created-at",
                    "created-by",
                    "modified-at",
                    "modified-by"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "allowlist"
    ],
    "type": "object"
}