API reference

This page is the HTTP reference for the factory surface of the TrustMint thingmake service. It renders the generated OpenAPI snapshot services/thingmake/docs/openapi/thingmake-openapi.yaml — the single source of truth produced by cmd/openapi-snapshot-gen. Do not transcribe operations from here; if something looks wrong, fix the generator and regenerate (see Contributing).

The four factory endpoint groups

A factory integrator works against four groups of endpoints:

Group

Prefix

What it does

factory-services

/api/v1/factory-services/*

Register and manage your factory-service backend; rotate its credentials; health-check and drain it.

things

/api/v1/things/*

Drive a device through its lifecycle — provision, activate, deactivate, annihilate — and read its state.

state-changes

/api/v1/state-changes

Poll the state-change feed (and manage state-change-subscriptions) to learn when a thing transitions.

identity-blacklist

/api/v1/identity-blacklist*

Query and manage blacklisted identities; pull signed snapshots + deltas for edge enforcement.

Authentication is FGAI-HMAC-SHA256 — the SigV4 algorithm, FGAI-branded, NOT aws-sdk-compatible. Factory-service calls are signed with an access-key / secret-key pair issued at registration. This is the AWS SigV4 derived-key-chain algorithm (the SigV4 mental model applies), but it is FGAI-branded — the chain terminates in fgai4_request and the scheme name is FGAI-HMAC-SHA256, so it is not wire-compatible with the stock aws-sdk signer: do not point an AWS SigV4 SDK at these endpoints. Use the generated SDKs, which implement the FGAI signing transport for you. (Same framing as registration Step 2 and the SDK README.)

Download the raw spec

For tooling import (Postman, openapi-generator, your own client codegen), download the raw generated spec directly:

Rendered reference

.. http:get:: /api/v1/access-requests

synopsis:

List access requests

List access requests

PDP action: thingmake:AccessRequest:List

Example request:

.. sourcecode:: http

GET /api/v1/access-requests HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

.. http:get:: /api/v1/access-requests/{id}

synopsis:

Read an access request

Read an access request

PDP action: thingmake:AccessRequest:Read

param string id:

Example request:

.. sourcecode:: http

GET /api/v1/access-requests/{id} HTTP/1.1
Host: example.com
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:post:: /api/v1/access-requests/{id}/approve

synopsis:

Approve an access request (sugar over Decide)

Approve an access request (sugar over Decide)

PDP action: thingmake:AccessRequest:Approve

param string id:

Example request:

.. sourcecode:: http

POST /api/v1/access-requests/{id}/approve HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:post:: /api/v1/access-requests/{id}/decide

synopsis:

Decide an access request (APPROVED or REJECTED)

Decide an access request (APPROVED or REJECTED)

PDP action: thingmake:AccessRequest:Decide

param string id:

Example request:

.. sourcecode:: http

POST /api/v1/access-requests/{id}/decide HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:post:: /api/v1/access-requests/{id}/reject

synopsis:

Reject an access request (sugar over Decide)

Reject an access request (sugar over Decide)

PDP action: thingmake:AccessRequest:Reject

param string id:

Example request:

.. sourcecode:: http

POST /api/v1/access-requests/{id}/reject HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:get:: /api/v1/enrollments

synopsis:

List enrollments (501 deferred to Phase 11)

List enrollments (501 deferred to Phase 11)

PDP action: thingmake:Enrollment:List

Example request:

.. sourcecode:: http

GET /api/v1/enrollments HTTP/1.1 Host: example.com

status 501:

Not Implemented (deferred)

Example response:

.. sourcecode:: http

HTTP/1.1 501 Not Implemented Content-Type: application/json

.. http:post:: /api/v1/enrollments

synopsis:

Create an enrollment (501 deferred to Phase 11)

Create an enrollment (501 deferred to Phase 11)

PDP action: thingmake:Enrollment:Create

Example request:

.. sourcecode:: http

POST /api/v1/enrollments HTTP/1.1 Host: example.com Content-Type: application/json

status 501:

Not Implemented (deferred)

Example response:

.. sourcecode:: http

HTTP/1.1 501 Not Implemented Content-Type: application/json

.. http:get:: /api/v1/enrollments/{id}

synopsis:

Read an enrollment (501 deferred to Phase 11)

Read an enrollment (501 deferred to Phase 11)

PDP action: thingmake:Enrollment:Read

param string id:

Example request:

.. sourcecode:: http

GET /api/v1/enrollments/{id} HTTP/1.1
Host: example.com
status 501:

Not Implemented (deferred)

Example response:

.. sourcecode:: http

HTTP/1.1 501 Not Implemented Content-Type: application/json

.. http:get:: /api/v1/factory-services

synopsis:

List factory_services (paginated, filterable by role/state/registrar/model)

List factory_services (paginated, filterable by role/state/registrar/model)

PDP action: thingmake:FactoryService:List

Example request:

.. sourcecode:: http

GET /api/v1/factory-services HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

.. http:post:: /api/v1/factory-services

synopsis:

Register a model-scoped factory backend (identify/provision); returns generated AK/SK once

Register a model-scoped factory backend (identify/provision); returns generated AK/SK once

PDP action: thingmake:FactoryService:Create

Example request:

.. sourcecode:: http

POST /api/v1/factory-services HTTP/1.1 Host: example.com Content-Type: application/json

status 201:

Created

Example response:

.. sourcecode:: http

HTTP/1.1 201 Created Content-Type: application/json

status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:delete:: /api/v1/factory-services/{id}

synopsis:

Soft-delete a factory_service (Phase 30 implements drain + GC)

Soft-delete a factory_service (Phase 30 implements drain + GC)

PDP action: thingmake:FactoryService:Delete

param string id:
status 204:

No Content

Example response:

.. sourcecode:: http

  HTTP/1.1 204 No Content
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/factory-services/{id}

synopsis:

Get a factory_service by id

Get a factory_service by id

PDP action: thingmake:FactoryService:Read

param string id:

Example request:

.. sourcecode:: http

GET /api/v1/factory-services/{id} HTTP/1.1
Host: example.com
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:patch:: /api/v1/factory-services/{id}

synopsis:

Update endpoint_url (only mutable field via PATCH)

Update endpoint_url (only mutable field via PATCH)

PDP action: thingmake:FactoryService:Update

param string id:

Example request:

.. sourcecode:: http

PATCH /api/v1/factory-services/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:post:: /api/v1/factory-services/{id}/confirm-rotation

synopsis:

Clear rotation_pending once the new credential is adopted; 409 if no rotation is pending

Clear rotation_pending once the new credential is adopted; 409 if no rotation is pending

PDP action: thingmake:FactoryService:ConfirmRotation

param string id:
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:post:: /api/v1/factory-services/{id}/expedite-drain

synopsis:

Expedite drain of a soft-deleted factory_service; hard-deletes if no active saga legs reference it

Expedite drain of a soft-deleted factory_service; hard-deletes if no active saga legs reference it

PDP action: thingmake:FactoryService:Drain

param string id:
status 204:

No Content

Example response:

.. sourcecode:: http

  HTTP/1.1 204 No Content
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:post:: /api/v1/factory-services/{id}/health-check

synopsis:

Synchronously probe endpoint_url /healthz; updates last_health_check_* columns

Synchronously probe endpoint_url /healthz; updates last_health_check_ columns*

PDP action: thingmake:FactoryService:HealthCheck

param string id:
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:post:: /api/v1/factory-services/{id}/rotate-credentials

synopsis:

Rotate AK/SK; returns new secret_access_key once and sets rotation_pending=true

Rotate AK/SK; returns new secret_access_key once and sets rotation_pending=true

PDP action: thingmake:FactoryService:RotateCredentials

param string id:
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/identity-blacklist

synopsis:

List all active identity-blacklist entries (paginated; sorted by model,sn)

List all active identity-blacklist entries (paginated; sorted by model,sn)

PDP action: thingmake:IdentityBlacklist:List

Example request:

.. sourcecode:: http

GET /api/v1/identity-blacklist HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

.. http:get:: /api/v1/identity-blacklist/check

synopsis:

Check if a (model, sn) pair is on the global identity blacklist

Check if a (model, sn) pair is on the global identity blacklist

PDP action: thingmake:IdentityBlacklist:Check

Example request:

.. sourcecode:: http

GET /api/v1/identity-blacklist/check HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/identity-blacklist/deltas

synopsis:

Poll the identity-blacklist delta feed since a cursor (72h TTL → HTTP 410)

Poll the identity-blacklist delta feed since a cursor (72h TTL → HTTP 410)

PDP action: thingmake:IdentityBlacklist:ListDeltas

Example request:

.. sourcecode:: http

GET /api/v1/identity-blacklist/deltas HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 410:

Response

Example response:

.. sourcecode:: http

HTTP/1.1 410 Gone Content-Type: application/json

.. http:get:: /api/v1/identity-blacklist/snapshot.signed

synopsis:

Download the JWS-signed identity-blacklist snapshot (application/jose+json) for fail-closed factory caching

Download the JWS-signed identity-blacklist snapshot (application/jose+json) for fail-closed factory caching

PDP action: thingmake:IdentityBlacklist:GetSnapshot

Example request:

.. sourcecode:: http

GET /api/v1/identity-blacklist/snapshot.signed HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 503:

Service Unavailable

Example response:

.. sourcecode:: http

HTTP/1.1 503 Service Unavailable Content-Type: application/json

.. http:get:: /api/v1/provisioning-runs

synopsis:

List provisioning runs

List provisioning runs

PDP action: thingmake:ProvisioningRun:List

Example request:

.. sourcecode:: http

GET /api/v1/provisioning-runs HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

.. http:get:: /api/v1/provisioning-runs/{id}

synopsis:

Read a provisioning run

Read a provisioning run

PDP action: thingmake:ProvisioningRun:Read

param string id:

Example request:

.. sourcecode:: http

GET /api/v1/provisioning-runs/{id} HTTP/1.1
Host: example.com
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/registrars

synopsis:

List registrars (keyset pagination)

List registrars (keyset pagination)

PDP action: thingmake:Registrar:List

Example request:

.. sourcecode:: http

GET /api/v1/registrars HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

.. http:post:: /api/v1/registrars

synopsis:

Create a registrar

Create a registrar

PDP action: thingmake:Registrar:Create

Example request:

.. sourcecode:: http

POST /api/v1/registrars HTTP/1.1 Host: example.com Content-Type: application/json

status 201:

Created

Example response:

.. sourcecode:: http

HTTP/1.1 201 Created Content-Type: application/json

status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 403:

Forbidden

Example response:

.. sourcecode:: http

HTTP/1.1 403 Forbidden Content-Type: application/json

.. http:delete:: /api/v1/registrars/{id}

synopsis:

Delete a registrar

Delete a registrar

PDP action: thingmake:Registrar:Delete

param string id:
status 204:

No Content

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/registrars/{id}

synopsis:

Read a registrar by id

Read a registrar by id

PDP action: thingmake:Registrar:Read

param string id:

Example request:

.. sourcecode:: http

GET /api/v1/registrars/{id} HTTP/1.1
Host: example.com
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:patch:: /api/v1/registrars/{id}

synopsis:

Update a registrar

Update a registrar

PDP action: thingmake:Registrar:Update

param string id:

Example request:

.. sourcecode:: http

PATCH /api/v1/registrars/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:post:: /api/v1/registrars/{id}/approve

synopsis:

Approve a pending registrar

Approve a pending registrar

PDP action: thingmake:Registrar:Approve

param string id:

Example request:

.. sourcecode:: http

POST /api/v1/registrars/{id}/approve HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:post:: /api/v1/registrars/{id}/reject

synopsis:

Reject a pending registrar

Reject a pending registrar

PDP action: thingmake:Registrar:Reject

param string id:

Example request:

.. sourcecode:: http

POST /api/v1/registrars/{id}/reject HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:get:: /api/v1/state-change-subscriptions

synopsis:

List webhook subscriptions for the authenticated registrar (paginated)

List webhook subscriptions for the authenticated registrar (paginated)

PDP action: thingmake:StateChangeSubscription:List

Example request:

.. sourcecode:: http

GET /api/v1/state-change-subscriptions HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

.. http:post:: /api/v1/state-change-subscriptions

synopsis:

Subscribe a factory webhook for state-change push notifications (acknowledge_polling_still_mandatory required; secret echoed once)

Subscribe a factory webhook for state-change push notifications (acknowledge_polling_still_mandatory required; secret echoed once)

PDP action: thingmake:StateChangeSubscription:Create

Example request:

.. sourcecode:: http

POST /api/v1/state-change-subscriptions HTTP/1.1 Host: example.com Content-Type: application/json

status 201:

Created

Example response:

.. sourcecode:: http

HTTP/1.1 201 Created Content-Type: application/json

status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 422:

Response

Example response:

.. sourcecode:: http

HTTP/1.1 422 Unprocessable Entity Content-Type: application/json

.. http:delete:: /api/v1/state-change-subscriptions/{id}

synopsis:

Soft-delete a webhook subscription

Soft-delete a webhook subscription

PDP action: thingmake:StateChangeSubscription:Delete

param string id:
status 204:

No Content

Example response:

.. sourcecode:: http

  HTTP/1.1 204 No Content
  Content-Type: application/json

  {}
status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/state-change-subscriptions/{id}

synopsis:

Get a webhook subscription by id (secret elided)

Get a webhook subscription by id (secret elided)

PDP action: thingmake:StateChangeSubscription:Read

param string id:

Example request:

.. sourcecode:: http

GET /api/v1/state-change-subscriptions/{id} HTTP/1.1
Host: example.com
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:patch:: /api/v1/state-change-subscriptions/{id}

synopsis:

Update a webhook subscription (target_url, event_filter, status ACTIVE/SUSPENDED, secret); SUSPENDED→ACTIVE resets failures

Update a webhook subscription (target_url, event_filter, status ACTIVE/SUSPENDED, secret); SUSPENDED→ACTIVE resets failures

PDP action: thingmake:StateChangeSubscription:Update

param string id:

Example request:

.. sourcecode:: http

PATCH /api/v1/state-change-subscriptions/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:post:: /api/v1/state-change-subscriptions/{id}/test

synopsis:

Synchronously POST a synthetic event to the subscription’s target_url; always returns 200 with {delivered, delivered_status, error}

Synchronously POST a synthetic event to the subscription’s target_url; always returns 200 with {delivered, delivered_status, error}

PDP action: thingmake:StateChangeSubscription:Test

param string id:
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/state-changes

synopsis:

Poll registrar-scoped state-changes feed (?since=; 72h TTL → HTTP 410; ?registrar_id= rejected with 400)

Poll registrar-scoped state-changes feed (?since=; 72h TTL → HTTP 410; ?registrar_id= rejected with 400)

PDP action: thingmake:StateChange:List

Example request:

.. sourcecode:: http

GET /api/v1/state-changes HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 410:

Response

Example response:

.. sourcecode:: http

HTTP/1.1 410 Gone Content-Type: application/json

.. http:get:: /api/v1/thingmake/models

synopsis:

List device models (keyset pagination)

List device models (keyset pagination)

PDP action: thingmake:Model:List

Example request:

.. sourcecode:: http

GET /api/v1/thingmake/models HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

.. http:post:: /api/v1/thingmake/models

synopsis:

Register a device model (vid:pid, provisioning-by-model)

Register a device model (vid:pid, provisioning-by-model)

PDP action: thingmake:Model:Create

Example request:

.. sourcecode:: http

POST /api/v1/thingmake/models HTTP/1.1 Host: example.com Content-Type: application/json

status 201:

Created

Example response:

.. sourcecode:: http

HTTP/1.1 201 Created Content-Type: application/json

status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:delete:: /api/v1/thingmake/models/{id}

synopsis:

Delete a device model

Delete a device model

PDP action: thingmake:Model:Delete

param string id:
status 204:

No Content

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/thingmake/models/{id}

synopsis:

Read a device model (public descriptor)

Read a device model (public descriptor)

PDP action: thingmake:Model:Read

param string id:

Example request:

.. sourcecode:: http

GET /api/v1/thingmake/models/{id} HTTP/1.1
Host: example.com
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:patch:: /api/v1/thingmake/models/{id}

synopsis:

Update a device model

Update a device model

PDP action: thingmake:Model:Update

param string id:

Example request:

.. sourcecode:: http

PATCH /api/v1/thingmake/models/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:post:: /api/v1/thingmake/models/{id}/share

synopsis:

Mint a share deeplink for a recipient factory (public descriptor only)

Mint a share deeplink for a recipient factory (public descriptor only)

PDP action: thingmake:Model:Share

param string id:

Example request:

.. sourcecode:: http

POST /api/v1/thingmake/models/{id}/share HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 201:

Created

Example response:

.. sourcecode:: http

  HTTP/1.1 201 Created
  Content-Type: application/json

  {}
status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/thingmake/models/{id}/software

synopsis:

Resolve the software/driver bundles applicable to a model’s vid:pid descriptor

Resolve the software/driver bundles applicable to a model’s vid:pid descriptor

PDP action: thingmake:Model:Read

param string id:

Example request:

.. sourcecode:: http

GET /api/v1/thingmake/models/{id}/software HTTP/1.1
Host: example.com
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:post:: /api/v1/thingmake/models/import

synopsis:

Import a shared model’s public descriptor via deeplink

Import a shared model’s public descriptor via deeplink

PDP action: thingmake:Model:Import

Example request:

.. sourcecode:: http

POST /api/v1/thingmake/models/import HTTP/1.1 Host: example.com Content-Type: application/json

status 201:

Created

Example response:

.. sourcecode:: http

HTTP/1.1 201 Created Content-Type: application/json

status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 403:

Forbidden

Example response:

.. sourcecode:: http

HTTP/1.1 403 Forbidden Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:get:: /api/v1/thingmake/software

synopsis:

List software/driver bundles (keyset pagination)

List software/driver bundles (keyset pagination)

PDP action: thingmake:Software:List

Example request:

.. sourcecode:: http

GET /api/v1/thingmake/software HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

.. http:post:: /api/v1/thingmake/software

synopsis:

Register a software/driver bundle and the vid:pid descriptor set it loads onto

Register a software/driver bundle and the vid:pid descriptor set it loads onto

PDP action: thingmake:Software:Create

Example request:

.. sourcecode:: http

POST /api/v1/thingmake/software HTTP/1.1 Host: example.com Content-Type: application/json

status 201:

Created

Example response:

.. sourcecode:: http

HTTP/1.1 201 Created Content-Type: application/json

status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:delete:: /api/v1/thingmake/software/{id}

synopsis:

Delete a software/driver bundle

Delete a software/driver bundle

PDP action: thingmake:Software:Delete

param string id:
status 204:

No Content

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/thingmake/software/{id}

synopsis:

Read a software/driver bundle + its applicability set

Read a software/driver bundle + its applicability set

PDP action: thingmake:Software:Read

param string id:

Example request:

.. sourcecode:: http

GET /api/v1/thingmake/software/{id} HTTP/1.1
Host: example.com
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:patch:: /api/v1/thingmake/software/{id}

synopsis:

Update a software/driver bundle (applies_to replaces the descriptor set)

Update a software/driver bundle (applies_to replaces the descriptor set)

PDP action: thingmake:Software:Update

param string id:

Example request:

.. sourcecode:: http

PATCH /api/v1/thingmake/software/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/thingmake/vendors

synopsis:

Read the account’s VID namespace

Read the account’s VID namespace

PDP action: thingmake:Vendor:Read

Example request:

.. sourcecode:: http

GET /api/v1/thingmake/vendors HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:post:: /api/v1/thingmake/vendors

synopsis:

Assign (or fetch) the account’s platform VID namespace

Assign (or fetch) the account’s platform VID namespace

PDP action: thingmake:Vendor:Assign

Example request:

.. sourcecode:: http

POST /api/v1/thingmake/vendors HTTP/1.1 Host: example.com Content-Type: application/json

status 201:

Created

Example response:

.. sourcecode:: http

HTTP/1.1 201 Created Content-Type: application/json

status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

.. http:get:: /api/v1/things

synopsis:

List things scoped to the authenticated registrar (paginated; ?state= filter; ?registrar_id= rejected with 400)

List things scoped to the authenticated registrar (paginated; ?state= filter; ?registrar_id= rejected with 400)

PDP action: thingmake:Thing:List

Example request:

.. sourcecode:: http

GET /api/v1/things HTTP/1.1 Host: example.com

status 200:

OK

Example response:

.. sourcecode:: http

HTTP/1.1 200 OK Content-Type: application/json

status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

.. http:get:: /api/v1/things/{id}

synopsis:

Get a thing by id (404 leakage-free on cross-registrar access)

Get a thing by id (404 leakage-free on cross-registrar access)

PDP action: thingmake:Thing:Read

param string id:

Example request:

.. sourcecode:: http

GET /api/v1/things/{id} HTTP/1.1
Host: example.com
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:post:: /api/v1/things/{id}/activate

synopsis:

Start ACTIVATE saga (PROVISIONED|DEACTIVATED → ACTIVATED, unified verb)

Start ACTIVATE saga (PROVISIONED|DEACTIVATED → ACTIVATED, unified verb)

PDP action: thingmake:Thing:Activate

param string id:
status 202:

Accepted

Example response:

.. sourcecode:: http

  HTTP/1.1 202 Accepted
  Content-Type: application/json

  {}
status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:post:: /api/v1/things/{id}/activation-result

synopsis:

Activation-leg result webhook

Activation-leg result webhook

PDP action: thingmake:Thing:Activate

param string id:

Example request:

.. sourcecode:: http

POST /api/v1/things/{id}/activation-result HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:post:: /api/v1/things/{id}/annihilate

synopsis:

Enter ANNIHILATION-PENDING (dual-control; second principal must confirm within 24h)

Enter ANNIHILATION-PENDING (dual-control; second principal must confirm within 24h)

PDP action: thingmake:Thing:Annihilate

param string id:
status 202:

Accepted

Example response:

.. sourcecode:: http

  HTTP/1.1 202 Accepted
  Content-Type: application/json

  {}
status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:post:: /api/v1/things/{id}/annihilate/confirm

synopsis:

Confirm ANNIHILATE (distinct principal); starts 3-leg saga

Confirm ANNIHILATE (distinct principal); starts 3-leg saga

PDP action: thingmake:Thing:Annihilate

param string id:
status 202:

Accepted

Example response:

.. sourcecode:: http

  HTTP/1.1 202 Accepted
  Content-Type: application/json

  {}
status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 403:

Forbidden

Example response:

.. sourcecode:: http

HTTP/1.1 403 Forbidden Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:post:: /api/v1/things/{id}/annihilation-result

synopsis:

Annihilation-leg result webhook

Annihilation-leg result webhook

PDP action: thingmake:Thing:Annihilate

param string id:

Example request:

.. sourcecode:: http

POST /api/v1/things/{id}/annihilation-result HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/things/{id}/audit

synopsis:

Get a thing’s state-transition audit trail (limit-capped at 200)

Get a thing’s state-transition audit trail (limit-capped at 200)

PDP action: thingmake:Thing:ReadAudit

param string id:

Example request:

.. sourcecode:: http

GET /api/v1/things/{id}/audit HTTP/1.1
Host: example.com
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:post:: /api/v1/things/{id}/deactivate

synopsis:

Start DEACTIVATE saga (ACTIVATED → DEACTIVATED, reversible kill-switch)

Start DEACTIVATE saga (ACTIVATED → DEACTIVATED, reversible kill-switch)

PDP action: thingmake:Thing:Deactivate

param string id:
status 202:

Accepted

Example response:

.. sourcecode:: http

  HTTP/1.1 202 Accepted
  Content-Type: application/json

  {}
status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:post:: /api/v1/things/{id}/deactivation-result

synopsis:

Deactivation-leg result webhook

Deactivation-leg result webhook

PDP action: thingmake:Thing:Deactivate

param string id:

Example request:

.. sourcecode:: http

POST /api/v1/things/{id}/deactivation-result HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:post:: /api/v1/things/{id}/provision

synopsis:

Start PROVISION saga (ROLLEDOFF → PROVISIONED)

Start PROVISION saga (ROLLEDOFF → PROVISIONED)

PDP action: thingmake:Thing:Provision

param string id:
status 202:

Accepted

Example response:

.. sourcecode:: http

  HTTP/1.1 202 Accepted
  Content-Type: application/json

  {}
status 400:

Validation failed

Example response:

.. sourcecode:: http

HTTP/1.1 400 Bad Request Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

status 409:

Conflict

Example response:

.. sourcecode:: http

HTTP/1.1 409 Conflict Content-Type: application/json

.. http:post:: /api/v1/things/{id}/provisioning-result

synopsis:

Provisioning-leg result webhook (factory backend)

Provisioning-leg result webhook (factory backend)

PDP action: thingmake:Thing:Provision

param string id:

Example request:

.. sourcecode:: http

POST /api/v1/things/{id}/provisioning-result HTTP/1.1
Host: example.com
Content-Type: application/json

{}
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json

.. http:get:: /api/v1/things/{id}/state

synopsis:

Get a thing’s current state + updated_at

Get a thing’s current state + updated_at

PDP action: thingmake:Thing:ReadState

param string id:

Example request:

.. sourcecode:: http

GET /api/v1/things/{id}/state HTTP/1.1
Host: example.com
status 200:

OK

Example response:

.. sourcecode:: http

  HTTP/1.1 200 OK
  Content-Type: application/json

  {}
status 401:

Unauthorized

Example response:

.. sourcecode:: http

HTTP/1.1 401 Unauthorized Content-Type: application/json

status 404:

Not Found

Example response:

.. sourcecode:: http

HTTP/1.1 404 Not Found Content-Type: application/json