API reference.

Authenticated health check

Confirms the API is reachable and your credential resolves an organization. Returns the resolved organizationId and actorType.

Responses

Response · 200

{
  "status": "ok",
  "organizationId": "string",
  "actorType": "api_key"
}

Ask a question about a project

The headline capability: a question in, a grounded answer out.

The assistant is interactive — when your question is ambiguous it can stop and ask rather than guessing. So a successful response is one of two shapes, discriminated by status:

• status: "answer" — the answer is ready.
• status: "needs_input" — the assistant needs questions answered first. Relay them to your user (or decide yourself — each carries a recommended_index hint), then call this endpoint again with the same conversation_id and an answers array. Nothing is guessed on your behalf.
• status: "unresolved" — the prompt asked to CHANGE the project rather than asking about it. reason names the code-proposal endpoint to use instead. Returned immediately, before any analysis is billed.

Two response modes off one endpoint:

• mode: "sync" (default) — a blocking JSON body.
• mode: "stream" — a Server-Sent Events stream (status / token / outcome / done / error). A turn that ends on questions emits outcome with them instead of prose. See the Streaming guide.

Requires the ai_explain permission. Platform coverage is the capability matrix in the API overview; where it says 422, the refusal lands before anything is metered.

Parameters

Request body required

{
  "prompt": "What conditions must be true for the main conveyor to start?",
  "mode": "sync"
}

Responses

Response · 200

status: "answer"

status: "needs_input"

The turn stopped to ask. Answer the questions and call again with the same conversation_id. This is a normal outcome, not an error.

status: "unresolved"

The request could not be served as asked. On proposeCode: nothing could be proposed — usually the request named something that isn't in the project, or described no anchorable change. On askProject: the prompt was a change request, and reason names the code-proposal endpoint.

Propose a code change (plan, then author)

Ask the assistant to PRODUCE or MODIFY PLC logic. Proposes, never deploys: no step here creates a version. To persist a proposal, commit it with POST /projects/{id}/versions (the separate code_write scope). Requires the ai_generate permission.

This is a two-step flow, because a change should be reviewed before it is written:

1. Send a prompt. You get status: "plan" — what would change, step by step, with any risks. No code is authored yet. 2. Show the plan to your user. If they approve, call again with the same conversation_id and approve: true (optionally with an amendment describing a tweak). You get status: "code" with the proposed changes.

The plan you approve is the one the server recorded in step 1 — it is not re-sent by you, so the change that gets authored is exactly the one that was reviewed.

A turn can also return status: "needs_input" (answer the questions and call again, as with askProject) or status: "unresolved" (nothing could be proposed; reason says what to do).

Two response modes off one endpoint:

• mode: "sync" (default) — a blocking JSON body.
• mode: "stream" — a Server-Sent Events stream (status / token / outcome / done / error). See the Streaming guide.

Platform coverage is the capability matrix in the API overview; where it says 422, the refusal lands before anything is metered.

Parameters

Request body required

{
  "prompt": "Add a 5-second start-up delay timer before the conveyor enables.",
  "target": {
    "program": "MainProgram",
    "routine": "ConveyorControl"
  },
  "mode": "sync"
}

Responses

Response · 200

status: "plan"

What the assistant would change. Nothing has been authored yet — call again with approve: true to author it.

status: "code"

The authored proposal. This creates NO version — commit it with POST /projects/{id}/versions (code_write) to persist it.

status: "needs_input"

The turn stopped to ask. Answer the questions and call again with the same conversation_id. This is a normal outcome, not an error.

status: "unresolved"

The request could not be served as asked. On proposeCode: nothing could be proposed — usually the request named something that isn't in the project, or described no anchorable change. On askProject: the prompt was a change request, and reason names the code-proposal endpoint.

Create a troubleshooting thread

Open a stateful multi-turn thread scoped to a project. Append turns with POST /conversations/{cid}/messages. Requires ai_explain.

A thread answers each turn exactly as interpret does, so it covers the same platforms — see the capability matrix in the API overview.

Parameters

Request body

{
  "name": "string"
}

Responses

Response · 201

{
  "conversationId": "string",
  "projectId": "string"
}

Append a turn to a thread

Run one interpret turn inside an existing thread. The thread's prior history is loaded automatically. Requires ai_explain.

Parameters

Request body required

{
  "prompt": "string",
  "answers": [
    {
      "id": "string",
      "selected_index": 0,
      "free_text": "string"
    }
  ]
}

Responses

Response · 200

status: "answer"

status: "needs_input"

The turn stopped to ask. Answer the questions and call again with the same conversation_id. This is a normal outcome, not an error.

status: "unresolved"

The request could not be served as asked. On proposeCode: nothing could be proposed — usually the request named something that isn't in the project, or described no anchorable change. On askProject: the prompt was a change request, and reason names the code-proposal endpoint.

Re-run the project's analysis

Run analysis again on the project's current version, and return immediately — the run continues in the background. Read the result with GET /projects/{id}/analysis.

This is the only verb on this surface that produces an analysis. A project uploaded in the app is analyzed there; a version committed with POST /projects/{id}/versions is not, so this is how a caller gets analysis onto a version it authored. It is a deliberate, billable act — analysis is expensive and per-version — which is why it is an HTTP operation rather than an agent tool.

Only one run exists per version at a time. If a healthy run is already in flight this joins it rather than scheduling a second: the response says started: false and no additional work (or spend) is incurred.

The run is not selectable: there is no request body, and every phase the project's detected industry calls for is executed. Which standards chapters appear therefore varies by project, not by request. Requires analysis_tab. Covers all three platforms.

Parameters

Responses

Response · 202

{
  "analysis_id": "string",
  "project_id": "string",
  "version_id": "string",
  "status": "queued",
  "started": true
}

Read the project's analysis

Return the analysis the platform already ran for this project — its current version by default, or the version version_id names. Nothing produces one as a side effect: it comes from analyzing the project in the app, or from an explicit POST /projects/{id}/analyses.

status is one of:

• not_analyzed — no analysis has ever run for this version. It will not start on its own; POST /projects/{id}/analyses produces one. This is a normal state, not an error, and it is the expected answer right after POST /projects/{id}/versions, which commits a version without analyzing it.
• queued / running — a run is in flight. The response carries a message with poll guidance and no results yet. Normal progress.
• complete — results holds the analysis. failed_phases may still be present when some phases failed but the run finished.
• error — the run failed; failed_phases names the phases that did.

When the current version is not_analyzed, the project's existing analysis is still reachable. The response then carries last_analyzed_version_id (and last_analyzed_at) naming the most recent version whose analysis completed — usually the version the last commit superseded. Pass that id back as ?version_id= to read it.

A version-pinned read serves that version's stored analysis and never substitutes it for the current one: the payload keeps naming the version it describes and carries is_current_version: false. Treat it as a statement about superseded code — report which version it describes and that the current version has not been analyzed, and remember only POST /projects/{id}/analyses produces a current one.

version_id resolves strictly inside the project in the path. A version belonging to another project — or another organization — returns 404, identical to an id that exists nowhere. A version that exists but was never analyzed is a normal 200 not_analyzed, not a 404.

For a cheap freshness check that returns no results blob, read analysis_status on GET /projects/{id} instead. Requires analysis_tab. Covers all three platforms.

Parameters

Responses

Response · 200

{
  "project_id": "string",
  "version_id": "string",
  "is_current_version": true,
  "status": "not_analyzed",
  "analyzed_at": "2026-05-31T18:15:00.000Z",
  "message": "string",
  "results": null,
  "failed_phases": [
    "string"
  ],
  "last_analyzed_version_id": "string",
  "last_analyzed_at": "2026-05-31T18:15:00.000Z"
}

Read one analysis run

Return the outcome of a single analysis run, by the analysis_id startAnalysis gave you.

This stays pinned to the version the run analysed. If a new version is committed while the run is in flight, this still reports *your* run, while GET /projects/{id}/analysis moves on to the new current version. is_current_version tells you directly whether the version this run analysed is still the project's live one — when it is false, these findings describe code the project no longer contains and must not be reported as its current state.

Not a run history: a version keeps only its most recent run id, so starting a second run on the same version makes the older id return 404. Requires analysis_tab. Rate-limited on the slow-job tier — an analysis takes minutes, so poll no faster than every 5 seconds.

Parameters

Responses

Response · 200

object

Export the project to its vendor PLC file

Start an async export of the project's current committed version to its native vendor format (a Rockwell .L5X, a Siemens TIA .zip or a CODESYS .export). Returns a job id immediately; poll GET /exports/{exportId} for status, then GET the download_url when complete. Exports the current version as-is (no edits). Requires export_plc.

A CODESYS export is written by patching the .export the version was uploaded from, so that file must still be in storage. When it is not, the job reaches status: "error" with a message saying so — the 202 only means the job was accepted, so always poll for the terminal state.

Parameters

Responses

Response · 202

{
  "exportId": "string",
  "status": "pending"
}

Render a PDF report for the project

Start an async render of a PDF documentation report for the project's current committed version. The report is assembled server-side from the parsed structure + analysis results (a "report-only" PDF; it does not include in-app chat history). Returns a job id immediately; poll GET /exports/{exportId} then GET the download_url. Requires export_pdf.

Which chapters appear depends on the platform and on whether an analysis has completed — see *What a PDF report contains differs by platform* under the capability matrix. A report rendered before any analysis run contains the structural chapters only.

Parameters

Responses

Response · 202

{
  "exportId": "string",
  "status": "pending"
}

Poll an export job

Return the current status of an export job. While pending/running the response carries a message with poll guidance. When complete, download_url (a relative /exports/{id}/download path) and filename are populated; when error, error carries a short reason. Gated on the export's matching permission (export_plc / export_pdf).

Parameters

Responses

Response · 200

{
  "exportId": "string",
  "kind": "plc",
  "status": "pending",
  "download_url": "string",
  "filename": "string",
  "error": "string",
  "message": "string"
}

Download a completed export artifact

Stream the finished artifact (L5X / Siemens ZIP / PDF) for a complete export job, with the right Content-Type and a Content-Disposition filename. Gated on the export's matching permission and scope.

Parameters

Responses

List projects

Enumerate the organization's active projects, most-recently-touched first. Requires only a valid key (no extra permission) — an ai_explain-only operator key still needs to discover which projects exist. Results are filtered to the key's project scope. Returns identity-level metadata only; read source via GET /projects/{id}/source.

Parameters

Responses

Response · 200

{
  "projects": [
    {
      "project_id": "string",
      "identity_id": "string",
      "name": "string",
      "vendor": "allen-bradley",
      "industry": "string",
      "file_type": "string",
      "current_version_id": "string",
      "updated_at": "2026-05-31T18:15:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Get a project

Identity + current-version metadata for one project, plus an analysis_status summary (not the full results blob). Requires only a valid key (no extra permission); scoped to the key's project scope. Unknown or out-of-scope id → 404.

Parameters

Responses

Response · 200

{
  "project_id": "string",
  "identity_id": "string",
  "name": "string",
  "display_name": "string",
  "vendor": "string",
  "industry": "string",
  "file_type": "string",
  "file_size_bytes": 0,
  "original_filename": "string",
  "current_version_id": "string",
  "version_number": 0,
  "analysis_status": "queued",
  "created_at": "2026-05-31T18:15:00.000Z",
  "updated_at": "2026-05-31T18:15:00.000Z"
}

Commit a new version (Save project)

Save a new version of an existing project from an updated vendor file — the headless equivalent of the platform's "Save project". The new version becomes the project's current version (billed identically to a UI save). Requires code_write.

It does not analyze. A commit is an authored edit, and analysis is expensive and per-version, so the new version starts out unanalyzed: the 201 carries analysis: "not_analyzed", and GET /projects/{id}/analysis reports the same until someone asks for a run with POST /projects/{id}/analyses. This matches the app, where the editor's Save does not analyze and Update Analysis is a separate action. Graph and search indexing DO run, so questions asked through interpret / conversations see the committed change immediately.

The uploaded file must be the same vendor as the project (an L5X stays L5X, a Siemens ZIP stays Siemens, a CODESYS .export stays .export) — a mismatch returns 400. Re-sending the exact bytes of the current version is a no-op: it returns 200 with resolution: identical_file and no new version.

Files up to ~4.5 MB may be sent inline as base64 in file.inline; larger files use the large-file flow via file.blob_url. A project-scoped key may only commit to in-scope projects.

Parameters

Request body required

{
  "originalFilename": "string",
  "name": "string",
  "file": {
    "inline": "string",
    "blob_url": "https://…"
  }
}

Responses

Response · 200

{
  "project_id": "string",
  "identity_id": "string",
  "version_id": "string",
  "version_number": 0,
  "resolution": "add_version",
  "vendor": "allen-bradley",
  "analysis": "not_analyzed"
}

Read a project's source

Return the project itself, in one of two representations. Requires code_read. There is deliberately nothing between them: the API serves whole-project reads and reasoning verbs, not fine-grained retrieval.

• format=parsed (default): the vendor-neutral parsed model as JSON — the same structure for all three platforms. Served straight from the stored artifact, so the response body is the parsed model, not an envelope around it. There is no size ceiling: the payload is never buffered into the response.
• format=raw: the current committed version's vendor file (L5X XML, Siemens ZIP or CODESYS .export), as a binary download. For a version saved in-app (where only the parsed model carries the edit) this is regenerated from the parsed model — the same bytes a PLC export produces — so it always reflects the latest committed state, not the originally uploaded file.

Both are served by streaming the stored object, or by a 302 to a short-lived storage URL where the backend offers one. Follow redirects.

Compression. Stored payloads are gzipped, and serving them that way is preferred — send Accept-Encoding: gzip and a parsed model arrives roughly 14x smaller. The response is then Content-Encoding: gzip; any client that advertises gzip inflates it transparently. A client that does NOT advertise gzip is served the decompressed bytes instead, so a plain request always yields directly usable content.

Parameters

Responses

Response · 200

object

{}

Latest live tag values

The most recent tag snapshot pushed by a Desktop Companion App (DCA) session for this project. Requires hmi_view. Returns data only while a DCA is actively streaming; with no live session, live is false and tags is empty (this is a normal 200, not an error).

Parameters

Responses

Response · 200

{
  "project_id": "string",
  "live": true,
  "message": "string",
  "device_id": "string",
  "timestamp": "2026-05-31T18:15:00.000Z",
  "controller": {
    "name": "string",
    "type": "string",
    "status": "string",
    "ipAddress": "string"
  },
  "sequence": 0,
  "tags": {
    "example_permission": null
  }
}

Recent value history for a tag

The most-recent-first value history a DCA session pushed for one tag. Requires hmi_view and a tag query parameter. Empty when no live session has streamed that tag.

Parameters

Responses

Response · 200

{
  "project_id": "string",
  "tag": "string",
  "count": 0,
  "history": [
    {
      "value": null,
      "timestamp": "2026-05-31T18:15:00.000Z",
      "sequence": 0
    }
  ]
}

Request live values for specific tags on demand

Ask the Desktop Companion App (DCA) serving this project to read a specific set of tags on its next poll — even if the operator never pressed "Start streaming" (the DCA only needs: connected + signed in + project selected). Requires hmi_edit.

This is a thin request signal, not a data read: it records the requested tag names and reports whether a DCA is currently able to serve them (live). Poll GET /projects/{id}/hmi/values (or interpret) a few seconds later to read the delivered values.

Naturally idempotent — re-requesting the same tags simply extends the request window — so no Idempotency-Key is required. The list is de-duped and never truncated, and maxItems declares the per-request ceiling, so a whole-project tag set can be requested in one call; unknown names are dropped by the DCA against its discovered tag list.

Parameters

Request body required

{
  "tags": [
    "string"
  ]
}

Responses

Response · 200

{
  "project_id": "string",
  "live": true,
  "requested": [
    "string"
  ]
}

Mint a read-only embed token

Mint a short-lived, project-scoped token for the embeddable read-only assistant iframe. Regardless of the minting key's scope, the token is intersected down to read-only (ai_explain + hmi_view) — a browser-delivered token can never carry a write scope. The minting key must itself have at least ai_explain.

Parameters

Request body required

{
  "project_id": "string"
}

Responses

Response · 201

{
  "token": "string",
  "expires_at": "2026-05-31T18:15:00.000Z",
  "permissions": {
    "example_permission": true
  },
  "project_id": "string"
}