The Structify API

Overview

The Structify API is a REST interface: you send HTTPS requests and receive JSON. Every API key belongs to exactly one organization and only reaches that organization's data.

Protocol

HTTPS, requests and responses as JSON (UTF-8)

Version

v1, part of every request path

Sign-in

API key in the X-Api-Key header

Areas

Projects, defects, reports, project file details, webhooks; plus legacy entries of the former site diary

Limit

1,000 requests per hour per key

Access & permissions

To connect, you need an API key that your management creates in the web app: Settings → Integrations → API & third parties (Einstellungen → Integrationen → API & Drittanbieter).

Permissions of a key

When you create a key, you choose what it may do. The server checks these permissions on every request:

The option "Export invoices" (Rechnungen exportieren) offered in the interface does not unlock any endpoint today.

Authentication

Send the key with every request in the X-Api-Key header. Alternatively, the API accepts it as a bearer token in the Authorization header.

X-Api-Key: <YOUR_API_KEY>

Authorization: Bearer <YOUR_API_KEY>

• Keys start with sk_. Structify shows a key only once, right after it is created. Copy it immediately.
• Only a check value (SHA-256) and the first characters for recognition are stored, not the key itself. Nobody can display it in full later; if you lose it, create a new key and deactivate the old one.
• When you deactivate a key in the settings, it becomes invalid immediately.

Base URL

Append every path on this page to this base URL:

https://api.structify.solutions/functions/v1/public-api

• Example: …/public-api/v1/projekte
• HTTPS only. The version (v1) is part of the path.
• Identifiers (id) are UUIDs; timestamps use ISO 8601 with a time zone, date fields use YYYY-MM-DD.
• Field names and values are passed through from Structify unchanged, so some field names and many values are German; error messages are in German. Exception: if registering a webhook fails in the database, the message may contain English database text.

Sample request

This is how you retrieve the first two projects of your organization:

curl "https://api.structify.solutions/functions/v1/public-api/v1/projekte?limit=2" \
  -H "X-Api-Key: <YOUR_API_KEY>"

const response = await fetch(
  "https://api.structify.solutions/functions/v1/public-api/v1/projekte?limit=2",
  { headers: { "X-Api-Key": process.env.STRUCTIFY_API_KEY } }
);
const body = await response.json();
if (!response.ok) throw new Error(`${body.status}: ${body.error}`);
const { data, total } = body;

{
  "data": [
    {
      "id": "<PROJECT_ID>",
      "project_name": "Neubau Bürogebäude Musterstraße",
      "project_number": "2026-014",
      "client_id": "<CLIENT_ID>",
      "clients": {
        "name": "Muster GmbH"
      },
      "project_type": "Neubau",
      "current_phase": "LP5",
      "status": "aktiv",
      "priority": "normal",
      "construction_start": "2026-03-02",
      "construction_end": "2027-06-30",
      "created_at": "2026-01-15T09:12:44.512+00:00"
    }
  ],
  "total": 12,
  "limit": 2,
  "offset": 0
}

Lists return data (entries), total (total number of matches), limit and offset, with one exception: GET /v1/webhooks returns data only. Single retrievals return data with all fields of the record.

Available endpoints

These endpoints work today. Paths are relative to the base URL; {id} stands for the identifier of the record.

Core concepts

Organization

Every key belongs to exactly one organization. Records of other organizations are not visible: single retrievals with a foreign identifier return 404.

Paging

limit sets the number of entries per response, offset the number of skipped entries. total gives the overall count, so you page until offset + limit ≥ total.

Sorting

Lists have a fixed order: newest first (former site diary by date descending; webhooks in no fixed order). The API does not offer custom sorting.

Filters

Filters compare for exact equality. A value that does not exist returns an empty list; an invalid identifier in a filter returns 400.

Responses

List: data, total, limit, offset (webhooks: data only) · Single retrieval: data · Create and update: data and message · Delete: message.

Methods

Reports, the former site diary and project files are read only. Send only GET to them: the API does not reject other methods there today but answers them like GET with the list; nothing is created or changed.

Rate limiting

Each key can make 1,000 requests per hour. The count covers the most recent 60 minutes, including requests that end with an error inside an endpoint (for example 400 or 404).

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997

When the limit is reached, the API responds with status 429:

{
  "error": "Rate Limit überschritten (1000/h)",
  "status": 429
}

Errors & status codes

Errors that the API itself detects are answered with a matching HTTP status and this JSON:

{
  "error": "API-Key fehlt. Header: X-Api-Key: sk_...",
  "status": 401
}

The status code is what counts. The message text is in German and may change, so do not evaluate it programmatically.

In case of operational disruptions, for example 502 or 504 after a timeout, the response may contain different JSON or none at all. In that case evaluate only the status and try again later. Before repeating POST /v1/tickets, check with GET whether the defect was created after all.

Webhooks

A webhook notifies your system of an event by HTTP POST to an address you specify. Today Structify sends exactly two events:

Structure of a message

data contains the stored record of the defect with all fields (shortened here; this includes the contact e-mail, the responsible company and notes), timestamp the time of sending.

POST /structify-webhook HTTP/1.1
Host: your-company.example
Content-Type: application/json
X-Structify-Signature: sha256=<HEX>

{
  "event": "ticket.status_geaendert",
  "data": {
    "id": "<DEFECT_ID>",
    "organization_id": "<ORGANIZATION_ID>",
    "project_id": "<PROJECT_ID>",
    "defect_number": "M-ERP-001",
    "building_location": "2. OG, Raum 2.14",
    "description": "Brandschutzklappe ohne Revisionsöffnung",
    "status": "behoben",
    "severity": "erheblich",
    "discipline": "Lüftung",
    "remediation_deadline": "2026-11-15",
    "created_at": "2026-10-08T07:41:03.118+00:00"
  },
  "timestamp": "2026-10-09T13:05:12.402Z"
}

Delivery

• Structify sends the message while the triggering API request is being processed. A slow receiver therefore delays that request's response.
• Time limit of 5 seconds per receiver; at most 10 webhooks per event. If more than 10 webhooks are registered for an event, which 10 are delivered is not defined.
• No retry on errors. GET /v1/webhooks shows the time and HTTP status of the last attempt (letzter_versuch, letzte_antwort; 0 means no response).
• Use HTTPS for the target address.

Verify the signature

The X-Structify-Signature header contains sha256= followed by the HMAC-SHA256 of the unmodified request body, computed with the webhook's signing secret. Compare in constant time:

import crypto from "node:crypto";

// rawBody: the unmodified request body, not re-serialized
export function isValidSignature(rawBody, signatureHeader, signingSecret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", signingSecret)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

The signature does not include a timestamp. If you want to reject replayed messages, also check the timestamp field.

Tutorials

First request in five steps

1. Sign in to the web app as a member of management and open Settings → Integrations → API & third parties.
2. Create a key with a descriptive name (for example "ERP connection") and select only the permissions your system needs.
3. Copy the key immediately (it is shown only once) and store it on your server, for example as the environment variable STRUCTIFY_API_KEY.
4. Call GET /v1/projekte as shown in the Sample request section.
5. Check the response: status 200, your projects in data and the remaining requests in X-RateLimit-Remaining.

Create and track defects from your system

You need a key with the Write tickets permission. Create the defect and keep the returned id:

curl -X POST "https://api.structify.solutions/functions/v1/public-api/v1/tickets" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"<PROJECT_ID>","defect_number":"M-ERP-001","building_location":"2. OG, Raum 2.14","description":"Brandschutzklappe ohne Revisionsöffnung","severity":"erheblich","discipline":"Lüftung","remediation_deadline":"2026-11-15"}'

{
  "data": {
    "id": "<DEFECT_ID>",
    "organization_id": "<ORGANIZATION_ID>",
    "project_id": "<PROJECT_ID>",
    "defect_number": "M-ERP-001",
    "building_location": "2. OG, Raum 2.14",
    "description": "Brandschutzklappe ohne Revisionsöffnung",
    "status": "offen",
    "severity": "erheblich",
    "discipline": "Lüftung",
    "remediation_deadline": "2026-11-15",
    "created_at": "2026-10-08T07:41:03.118+00:00"
  },
  "message": "Ticket erstellt"
}

Later you set the status, which triggers the ticket.status_geaendert event:

curl -X PUT "https://api.structify.solutions/functions/v1/public-api/v1/tickets/<DEFECT_ID>" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"status":"behoben"}'

Retrieve the open defects of a project, filtered and page by page:

curl "https://api.structify.solutions/functions/v1/public-api/v1/tickets?projekt_id=<PROJECT_ID>&status=offen&limit=50&offset=0" \
  -H "X-Api-Key: <YOUR_API_KEY>"

{
  "data": [
    {
      "id": "<DEFECT_ID>",
      "defect_number": "M-ERP-001",
      "building_location": "2. OG, Raum 2.14",
      "description": "Brandschutzklappe ohne Revisionsöffnung",
      "status": "offen",
      "severity": "erheblich",
      "discipline": "Lüftung",
      "remediation_deadline": "2026-11-15",
      "project_id": "<PROJECT_ID>",
      "created_at": "2026-10-08T07:41:03.118+00:00",
      "projects": {
        "project_name": "Neubau Bürogebäude Musterstraße"
      }
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Set up a webhook and verify the signature

Register the webhook through the API and store signing_secret from the response securely on your server:

curl -X POST "https://api.structify.solutions/functions/v1/public-api/v1/webhooks" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name":"ERP-Anbindung","url":"https://your-company.example/structify-webhook","events":["ticket.erstellt","ticket.status_geaendert"]}'

{
  "data": {
    "id": "<WEBHOOK_ID>",
    "name": "ERP-Anbindung",
    "url": "https://your-company.example/structify-webhook",
    "events": [
      "ticket.erstellt",
      "ticket.status_geaendert"
    ],
    "ist_aktiv": true
  },
  "message": "Webhook registriert",
  "signing_secret": "<SIGNING_SECRET>"
}

Verify the signature of every incoming message (see the Webhooks section) and respond within 5 seconds with a 2xx status.

What the API cannot do today

So that you can plan reliably, we state openly what the interface does not offer today:

• Read or write entries from "Project Tickets" (Projekttickets) or warranty defects from "Warranty Defects" (Gewährleistungsmangel).
• Read or write site diary entries that you create today as a project ticket of the type "Site diary entry" (Bautagebuch-Eintrag). GET /v1/bautagebuch returns only legacy entries of the former site diary area.
• Read documents created from templates in the project area "Protocols & Forms" (for example notices of defects, notices of obstruction or minutes), or meeting minutes from "Basic Assessment", "Planning Meeting" and "Site Meeting".
• Assign defect numbers automatically.
• Create or update projects; projects are read only.
• A full-text search across projects.
• Download or upload files; transfer photos, plans and attachments.
• Retrieve details of plans or of photos from the photo gallery; /v1/dokumente covers only the document database.
• Create or update reports, entries of the former site diary or file details.
• Retrieve users, roles and members; retrieve contacts, invoices, fee calculation, contract award and change orders as separate areas. Fee, budget and billing details and contact persons stored in the project itself are, however, included in a single retrieval of a project.
• Webhooks for changes in the web app or in Structify on iPhone & Android; redelivery of failed webhooks.
• Sign-in via OAuth, personal access tokens or keys restricted to individual projects.
• A test environment, a machine-readable interface description (OpenAPI) or ready-made client libraries.

Changelog

1. 8 Oct 2026 In the web app, API keys and webhooks are now managed by management only. A key is valid only as long as the person who created it is an active member of management.
2. 6 Oct 2026 New base URL https://api.structify.solutions/functions/v1/public-api after operations moved to Hetzner in Germany. The previous address is no longer reachable.