1wire API — Documentation

1. Overview

The 1wire API gives you the latest saved version of the projects in your account. Each API token belongs to one account and gives access to all projects in that account, whichever user created them.

Base URL

All endpoints in this documentation live under:

https://app.1wire.be/api/v1

The API is also available on the Dutch and French domains (app.1draad.be and app.1filaire.be). The domain has no effect on the data you get back.

What v1 does not do

• Changes that have not been saved yet, or that are stored offline in the browser, are not in the API.
• You cannot create, change or delete projects: the API is read-only.
• You manage tokens in the app, not through the API.

OpenAPI specification

The full machine-readable contract is at app.1wire.be/api/v1/openapi.yaml. Load it into Postman, Insomnia or a code generator to build a client.

MCP for AI assistants

You can also open the same data to an AI assistant through MCP. You simply sign in with your account; no API token needed.

2. Authentication

Create an API token

1. Sign in at app.1wire.be.
2. Open the user menu at the top right, choose Integrations (below Users) and open the REST API tab.
3. Give the token a recognisable name, for example the name of your ERP integration, and click Create token.
4. Copy the token straight away. The full token is shown only once.

A token belongs to the account, not to the user who created it. It stays valid until someone revokes it or the account is deleted, even if the user who created it leaves the account. Every user in the account can see, create and revoke all tokens. The same page shows when each token was last used.

Sending the token

Send the token in the Authorization header with every request:

curl https://app.1wire.be/api/v1/projects \
  -H "Authorization: Bearer $DENDRAAD_API_TOKEN"

• A token in a query parameter is not accepted, and a signed-in browser session does not give access to the API.
• If the token is missing, invalid or revoked, you get 401 with a WWW-Authenticate: Bearer realm="1draad API" header.
• All responses carry Cache-Control: no-store.

3. List projects

Returns all non-deleted projects in the account, from every user, newest first (created_at descending, then id descending).

Query parameters

curl "https://app.1wire.be/api/v1/projects?per_page=100&query=ERP-101" \
  -H "Authorization: Bearer $DENDRAAD_API_TOKEN"

{
  "data": [
    {
      "id": 123,
      "name": "Home battery installation",
      "reference": "ERP-101",
      "client_name": "Sarah Janssens",
      "installation_ean": "541234567890123456",
      "created_at": "2026-10-23T09:00:00.000000Z",
      "updated_at": "2026-10-23T10:00:00.000000Z",
      "app_url": "https://app.1wire.be/projects/123/edit",
      "share_url": null
    }
  ],
  "pagination": { "page": 1, "per_page": 100, "total_count": 1, "total_pages": 1 }
}

Project fields

Links use the domain of the project's export language: app.1draad.be, app.1filaire.be or app.1wire.be.

Pagination

The list uses numbered pages. If projects are added or removed while you page through, a project can shift to another page and show up twice or not at all. Always deduplicate on id, and see Syncing for a robust approach.

4. Project details

Returns all fields from the list, plus the project's administrative details and four contact records.

Every contact record has the same fields: name, street, postal_code, city, country, company_number, fixed_phone, mobile_phone and email. Anything not filled in stays null or empty.

{
  "data": {
    "id": 123,
    "name": "Home battery installation",
    "reference": "ERP-101",
    "client_name": "Sarah Janssens",
    "installation_ean": "541234567890123456",
    "created_at": "2026-10-23T09:00:00.000000Z",
    "updated_at": "2026-10-23T10:00:00.000000Z",
    "app_url": "https://app.1wire.be/projects/123/edit",
    "share_url": null,
    "account_id": 7,
    "owned_by_id": 15,
    "client_language": "en",
    "installation_kind": "domestic",
    "installation_same_as_client": true,
    "current_type": "3 x 400V + N ~ 50Hz",
    "client": {
      "name": "Sarah Janssens",
      "street": "Avenue Louise 120",
      "postal_code": "1050",
      "city": "Brussels",
      "country": "Belgium",
      "company_number": null,
      "fixed_phone": null,
      "mobile_phone": "0470 12 34 56",
      "email": "[email protected]"
    },
    "installation_location": { "name": null, "street": null, ... },
    "installer": { ... },
    "controller": { ... }
  }
}

5. Read the single-line diagram

Returns a readable view of the saved diagrams: every component with its settings, the circuit it belongs to, and the notes. The response comes from one saved version of the project and changes nothing in the project.

{
  "data": {
    "project_id": 123,
    "updated_at": "2026-10-23T10:00:00.000000Z",
    "property_units": { "amperage": "A", "delta_current": "mA", "cross_section": "mm²", "length": "m" },
    "schematics": [
      {
        "id": "schema-1",
        "name": "Schema 1",
        "root_component_ids": ["board-789"],
        "components": [ ... ],
        "annotations": [
          { "id": "note-1", "anchor_component_id": "battery-123", "text": "Installed in the garage" }
        ],
        "backup_connections": [
          { "id": "backup-1", "converter_component_id": "converter-456", "switchboard_component_id": "board-789" }
        ]
      }
    ]
  }
}

Diagrams

A project can contain several diagrams. Each diagram in schematics has:

Components

{
  "id": "battery-123",
  "type": "battery",
  "label": "Battery",
  "description": "Brand: Example\nS/N: BAT-001",
  "properties": { "quantity": 1, "label": "B1" },
  "parent_id": "converter-456",
  "child_ids": [],
  "connection": {},
  "switchboard_id": "board-789",
  "circuit_id": "breaker-234",
  "circuit_label": "B",
  "circuit_name": "Home battery circuit",
  "phase": "L1",
  "subcircuit_id": "battery-123",
  "subcircuit_label": 1,
  "subcircuit_name": null
}

Units

property_units tells you the unit of known settings:

Identity and consistency

A component is unique within the combination (project_id, schematic_id, component_id). If you fetch project details and the diagram in separate requests, compare updated_at to make sure they belong to the same saved version.

6. Syncing

To keep your own system up to date, regularly request the projects that changed since the previous run:

1. Note the time before you start.
2. Page through all of GET /projects?updated_since=… with the time of the previous run, and deduplicate on id.
3. For each changed project, fetch the details or the diagram if you need them.
4. Store the time from step 1 as the starting point for the next run. Because updated_since is inclusive, you miss nothing; a project that arrives twice is simply overwritten.

const BASE_URL = "https://app.1wire.be/api/v1";
const headers = { Authorization: `Bearer ${process.env.DENDRAAD_API_TOKEN}` };

// All projects changed at or after `since`, deduplicated on id.
async function changedProjects(since) {
  const projects = new Map();
  for (let page = 1; ; page++) {
    const url = new URL(`${BASE_URL}/projects`);
    url.search = new URLSearchParams({ page, per_page: 100, updated_since: since });
    const response = await fetch(url, { headers });
    const body = await response.json();
    if (!response.ok) throw new Error(`${body.error.code}: ${body.error.message}`);

    body.data.forEach((project) => projects.set(project.id, project));
    if (page >= body.pagination.total_pages) return [...projects.values()];
  }
}

7. MCP for AI assistants

The same data is also available as an MCP server (Model Context Protocol). An AI assistant that supports MCP, such as Claude or ChatGPT, can then look up your projects and read your diagrams itself, for example to draw up a material list or answer a question about an installation.

https://app.1wire.be/mcp

The server uses the Streamable HTTP transport and is also available on app.1draad.be and app.1filaire.be. You can connect in two ways: by signing in with your 1wire account (recommended), or with an API token.

Connect by signing in (recommended)

No token needed. You sign in and approve each AI client yourself.

1. Add the URL above as a remote MCP server (Streamable HTTP) in your AI client. Choose OAuth if the client asks how to authenticate.
2. Sign in with your existing 1wire account when the client asks.
3. Check the account and the callback address, then click Allow read-only access. The client then appears under Integrations → AI assistants (MCP) → Connected AI clients.

claude mcp add --transport http 1wire https://app.1wire.be/mcp
# Then in Claude Code: /mcp, choose 1wire and sign in.

codex mcp add 1wire --url https://app.1wire.be/mcp
codex mcp login 1wire
# Opens your browser to sign in.

ChatGPT: in Settings, turn on Developer mode under Apps → Advanced settings. Then choose Apps → Create, enter the MCP URL, choose OAuth as the authentication and sign in. Whether and where this is available depends on your ChatGPT plan; in a workspace an admin may need to allow it first.

• The client can read all saved projects, contact details and diagrams in the account. It cannot change projects or enable sharing.
• You approve every connection yourself, even if the same client has connected before. The client name comes from the client itself and is not verified: only approve connections you started.
• Any user in the account can revoke a connection with Disconnect. The client loses access straight away; other connections and API tokens keep working.
• A connection belongs to the user who approved it. If that user leaves the account, the connection ends too. After 90 days it always expires and you connect again.
• Sign-in applies per domain: a connection through app.1wire.be does not work on app.1draad.be or app.1filaire.be, and it does not give access to the REST API.

Connect with an API token

Client can't sign in but supports a custom Authorization header? Send an API token as a Bearer token instead, as with the REST API (see Authentication).

{
  "mcpServers": {
    "1wire": {
      "url": "https://app.1wire.be/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    }
  }
}

Tools

All tools are read-only and return the same JSON response as the matching REST endpoint.

The result is returned both in structuredContent and as JSON text in content, so clients without support for structured results can read it too. Descriptions and notes in a project are user data; the server asks AI clients not to treat them as instructions.

Errors

• An unknown, deleted or foreign project, or an invalid argument, returns a tool result with isError: true and the same error object as the REST API (not_found or invalid_parameters).
• An unknown tool or method returns a JSON-RPC protocol error.
• Without a valid API token or OAuth access token you get HTTP 401, with a WWW-Authenticate header that points to the server's OAuth metadata.

Technical details

You only need this if you build an MCP client yourself.

Transport

• Supports MCP protocol version 2025-11-25 and the earlier versions of the official MCP Ruby SDK. Send initialize first, then notifications/initialized, and afterwards pass the negotiated version in the MCP-Protocol-Version header. An unsupported version returns HTTP 400.
• Every POST carries Content-Type: application/json and Accept: application/json, text/event-stream. Responses are JSON; a notification gets an empty response with HTTP 202.
• The server is stateless: no session ID, no persistent SSE stream. GET and DELETE return HTTP 405.
• Native clients without an Origin header are welcome. With an Origin header, only the three app domains are accepted; others return HTTP 403. Calling it directly from a web page on another domain (CORS) therefore does not work.

OAuth

• Only the authorization-code flow with PKCE (S256), required for every client. The only scope is mcp:read.
• Register your client with client_name, exact redirect_uris and token_endpoint_auth_method (none, client_secret_basic or client_secret_post). Callback addresses must use HTTPS, except HTTP on a loopback address for native clients. Client ID Metadata Documents are not supported yet.
• Pass the MCP URL as the resource parameter, for example https://app.1wire.be/mcp. Token requests use application/x-www-form-urlencoded.
• An access token is valid for one hour. Every refresh returns a new access token and a new refresh token; store both and never refresh twice at the same time. Reusing an old refresh token revokes the whole connection.

curl https://app.1wire.be/mcp \
  -H "Authorization: Bearer $DENDRAAD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call",
           "params":{"name":"list_projects","arguments":{"query":"ERP-101","per_page":10}}}'

8. Errors

On an error you get a JSON object with a fixed code and a message. Base your logic on the code, not on the text.

{ "error": { "code": "not_found", "message": "Project not found." } }

9. Versions and compatibility

Changes that could break existing integrations will arrive in a new namespace (/api/v2). Within v1, things can still be added. Write your integration so it tolerates:

• new fields in a response,
• new component types in type,
• new settings in properties and connection.

Questions about the API, or missing a piece of data for your integration? Let us know through the contact form.