> ## 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.

# GET /machines/{machine_id}

> Return a peaqOS Machine Card for a machine identified by its numeric machine ID.

## Endpoint

```http theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
GET /machines/{machine_id}
```

Returns a peaqOS Machine Card for a registered machine. The Machine Card follows the ERC-8004 agent registration file pattern, restyled with peaqOS terminology, and includes identity, services, operator, bond status, and registry references.

## Path parameters

<ParamField path="machine_id" type="integer" required default="1">
  On-chain machine ID (not an NFT token ID and not a DID)
</ParamField>

## Response

**200 OK**

| Field                             | Type           | Description                                                                                                                         |
| :-------------------------------- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `type`                            | string         | peaqOS registration type: `"peaqos:registration:v1"`                                                                                |
| `name`                            | string         | `"Machine #<machine_id>"`                                                                                                           |
| `description`                     | string         | Fixed string: `"peaqOS machine"`                                                                                                    |
| `did`                             | string         | Machine DID derived from the machine wallet address (`did:peaq:<wallet_address>`)                                                   |
| `active`                          | boolean        | Always `true` for registered machines                                                                                               |
| `services`                        | array          | List of service endpoints. Contains one `"web"` entry if a `data_api` attribute is configured on the DID document; otherwise empty. |
| `services[].name`                 | string         | `"web"`                                                                                                                             |
| `services[].endpoint`             | string         | Value of the `data_api` DID attribute                                                                                               |
| `data_visibility`                 | string         | `"private"`, `"onchain"`, or `"public"`. Defaults to `"private"` if the DID document has no `data_visibility` attribute.            |
| `documentation_url`               | string         | Documentation URL from the DID document. Empty string if not set.                                                                   |
| `operator`                        | string or null | Operator DID from the DID document                                                                                                  |
| `bond_status`                     | string         | `"bonded"` or `"unbonded"`                                                                                                          |
| `event_count`                     | integer        | Total on-chain event count                                                                                                          |
| `registrations`                   | array          | List of registry references (always one entry)                                                                                      |
| `registrations[].type`            | string         | `"peaqos:registration:v1"`                                                                                                          |
| `registrations[].machineId`       | integer        | The machine's on-chain ID                                                                                                           |
| `registrations[].machineRegistry` | string         | CAIP-compatible registry identifier: `eip155:<chainId>:<registryAddress>`                                                           |

The `chainId` in `machineRegistry` is read from the connected RPC node at server startup (default `3338` for peaq mainnet). The `registryAddress` is the IdentityRegistry contract address.

## Error responses

| Status | `detail`                     | Condition                                                          |
| :----- | :--------------------------- | :----------------------------------------------------------------- |
| 404    | `"Machine not found"`        | Machine ID does not exist in the IdentityRegistry contract         |
| 404    | `"Machine wallet not found"` | The machine's wallet address is the zero address (`0x0000...0000`) |
| 422    | (FastAPI validation error)   | `machine_id` is less than 1 or not an integer                      |
| 503    | `"Service not initialised"`  | Server started without contract addresses                          |
| 503    | `"Chain unavailable"`        | Any chain or DID call failed                                       |

## Example

<CodeGroup>
  ```bash bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  curl "${PEAQOS_MCR_API_URL}/machines/42"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  const response = await fetch(`${PEAQOS_MCR_API_URL}/machines/42`);
  const data = await response.json();
  console.log(data.name, data.bond_status, data.registrations);
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import requests

  response = requests.get(f"{PEAQOS_MCR_API_URL}/machines/42")
  data = response.json()
  print(data["name"], data["bond_status"], data["registrations"])
  ```
</CodeGroup>

**Response**

```json theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
{
  "type": "peaqos:registration:v1",
  "name": "Machine #42",
  "description": "peaqOS machine",
  "did": "did:peaq:0xabc1230000000000000000000000000000000001",
  "active": true,
  "services": [
    {
      "name": "web",
      "endpoint": "https://machine.example.com/api/data"
    }
  ],
  "data_visibility": "private",
  "documentation_url": "https://example.com/docs",
  "operator": "did:peaq:0xoperator0000000000000000000000000000001",
  "bond_status": "bonded",
  "event_count": 150,
  "registrations": [
    {
      "type": "peaqos:registration:v1",
      "machineId": 42,
      "machineRegistry": "eip155:3338:0xIdentityRegistryAddress0000000000000001"
    }
  ]
}
```

## Related endpoints

* [GET /machine/{did}](/peaqos/api-reference/get-machine) returns the full machine profile with MCR score and data visibility-dependent fields.
* [GET /mcr/{did}](/peaqos/api-reference/get-mcr) returns the detailed MCR score, revenue trend, and revenue summary.
* [GET /metadata/{token_id}](/peaqos/api-reference/get-metadata) returns NFT metadata for a MachineNFT token.