Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt

Use this file to discover all available pages before exploring further.

These endpoints register and update machine records in the orchestration service. When PEAQOS_MACHINE_IDENTITY_VERIFICATION=required is on (production default), the caller must include a signed EIP-191 controller proof obtained from a challenge before the orchestrator will persist any machine-bound write. See the Machine Markets overview for base path, auth model, common envelopes, and error codes.

​
Machine type

type Machine = {
  id: string;
  displayName: string;
  status: "draft" | "active" | "degraded" | "blocked" | "archived";
  ownerId: string;
  identityRef: string;          // did:peaq:0x... or peaqos:machine:<id>
  identityProof?: {
    method: "eip191";
    identityRef: string;
    signerAddress: string;
    challengeId: string;
    verifiedAt: string;
    challengeExpiresAt: string;
    controllerAddresses: string[];
    resolutionSource: "peaqos-mcr";
  } | null;
  machineType: string;
  runtimeProfile: string;
  capabilities: string[];
  labels: Record<string, string>;
  policyIds: string[];
  skillKeys: string[];
  createdAt: string;
  updatedAt: string;
};

​
Machine identity

​
POST /machine-identity/challenges

Creates a short-lived challenge for a peaqOS machine identity. The caller signs message with the DID-controller private key and submits { challengeId, signature } as identityProof when creating or updating the machine. 
type CreateMachineIdentityChallengeRequest = {
  identityRef: string; // did:peaq:0x... or peaqos:machine:<id>
};

type CreateMachineIdentityChallengeResponse = ItemResponse<{
  challengeId: string;
  identityRef: string;
  message: string;
  expiresAt: string;
  verificationMethod: "eip191";
  controllerAddresses: string[];
}>;

type MachineIdentityProofInput = {
  challengeId: string;
  signature: string;     // EIP-191 personal_sign
};
Challenges expire. If a proof is submitted past expiresAt the orchestrator returns MACHINE_IDENTITY_PROOF_EXPIRED and the caller must re-challenge.

​
Machines

​
GET /machines

Only returns machines whose identityRef resolves and whose stored identityProof matches MCR controller data. Draft machines without a verified proof are filtered out. 
type ListMachinesResponse = ListResponse<Machine>;

​
POST /machines

Creates a machine record. Requires identityProof when identity verification is enabled. 
type CreateMachineRequest = {
  displayName: string;
  ownerId: string;
  machineType: string;
  runtimeProfile: string;
  identityRef: string;
  identityProof?: MachineIdentityProofInput;
  capabilities?: string[];
  labels?: Record<string, string>;
  policyIds?: string[];
  skillKeys?: string[];
};

type CreateMachineResponse = ItemResponse<Machine>;
Errors: MACHINE_IDENTITY_PROOF_REQUIRED, MACHINE_IDENTITY_PROOF_INVALID, MACHINE_IDENTITY_PROOF_EXPIRED, MACHINE_IDENTITY_EXISTS, PEAQOS_IDENTITY_UNAVAILABLE, VALIDATION_ERROR.

​
GET /machines/:machineId

The orchestrator re-verifies the persisted identity proof against peaqOS MCR data on every read. Returns MACHINE_NOT_ACTIVATED if the machine no longer resolves through MCR. 
type GetMachineResponse = ItemResponse<Machine>;

​
PATCH /machines/:machineId

Partial update. identityRef is immutable once set; attempting to change it returns MACHINE_IDENTITY_IMMUTABLE. Identity proofs are re-verified on every update. Activating an unverified machine returns MACHINE_NOT_ACTIVATED. Submitting a proof that does not recover to an MCR controller returns MACHINE_IDENTITY_PROOF_INVALID. MCR resolution failures return PEAQOS_IDENTITY_UNAVAILABLE. 
type UpdateMachineRequest = Partial<CreateMachineRequest> & {
  status?: Machine["status"];
};

type UpdateMachineResponse = ItemResponse<Machine>;