> For the complete documentation index, see [llms.txt](https://docs.protoboard.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.protoboard.xyz/reference/protoboard-file-format.md).

# .protoboard file format

What a .protoboard file contains, how it relates to ProtoPart, and how to export, import and open board files

## Goal

Know what's inside a board file and what you can do with one.

## What it is

A `.protoboard` file is one complete board saved as JSON (media type `application/x-protoboard+json`). It contains:

* **Board metadata**: name, author and timestamps
* **Parts** and their **part templates** (full ProtoPart definitions, including your local edits)
* **Harnesses**, interface links, function links and pin allocations
* **Groups**, **notes** and note connections, and the canvas layout
* **Board Identity**: description, tags, requirements, tasks and notes
* **BOM** customizations and supplier records

It doesn't include sharing settings, members, version history or ProtoBot chats.

The top level wraps the board with a schema version:

```json
{
  "schemaVersion": "1.19.0",
  "board": {
    "metadata": { "name": "Sensor test rig" },
    "partsById": {},
    "harnessesById": {},
    "templateState": {},
    "boardIdentity": {}
  }
}
```

Part templates inside the file follow the open [ProtoPart schema](https://docs.protoboard.xyz/reference/protopart-schema.md). Newer versions of Protoboard read files from older versions and upgrade them as they load.

## Export and import

| Action | Where                                                                                                                                                                                     |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Export | Editor **Project menu > Export to File** downloads `<board name>.protoboard`                                                                                                              |
| Import | **Project menu > Import from File**, then pick a `.protoboard` or `.json` file, or **Paste board JSON instead**                                                                           |
| Agents | `export_board` and `import_board` over the [Agent Bridge](https://docs.protoboard.xyz/agent-bridge/tool-reference.md). Importing through an agent replaces the connected board's contents |

An import in the app opens as a new local draft with a new board ID, so it never overwrites an existing board. Save it to the cloud to keep it. See [Bring in an existing design](https://docs.protoboard.xyz/tutorials/bring-in-an-existing-design.md).

{% hint style="info" %}
If you install Protoboard as an app from your browser, you can open `.protoboard` files straight from your computer's file manager.
{% endhint %}

## Common failures

<details>

<summary>The file won't import</summary>

It isn't valid JSON, or it isn't a board. Re-export it from the source board rather than editing it by hand.

</details>

<details>

<summary>An agent's export_board fails on a large board</summary>

Very large boards can be too big to pass through the Agent Bridge. Export them from the app's Project menu instead.

</details>

## Related pages

* [Bring in an existing design](https://docs.protoboard.xyz/tutorials/bring-in-an-existing-design.md)
* [Saving, drafts and recovery](https://docs.protoboard.xyz/organize/saving-and-drafts.md)
* [ProtoPart Schema](https://docs.protoboard.xyz/reference/protopart-schema.md)
