Guide · HTTP API

Any documented API, bounded.

Upload an OpenAPI description. Ardyn imports the operations it supports, calls none of them, and lets you enable reads and version-bound updates. If a response is lost after a change was sent, Ardyn reads the target to find out what happened — it never sends the change again.

Supported import

VersionsOpenAPI 3.0.x and 3.1.x, JSON or YAML, ≤ 2 MiB, uploaded in the request

OperationsOnly real operation keys (get, put, post, delete, options, head, patch, trace). Path-item parameters apply to each operation; servers, summary, $ref and x-* are never operations.

ParametersPath, query and non-credential header parameters (scalar values); application/json bodies validated against the schema

ReferencesLocal #/components/… only. Remote references are disabled.

Effect classGET/HEAD/OPTIONS import as read; everything else as write. A write can’t be enabled as read.

Tested withA previously unlisted record API over a real local transport, including an injected lost response — 19 of 19 cases

Rejected, with the reason

Swagger / OpenAPI 2.0
Remote $ref
multipart and form bodies (the operation is skipped and listed)
Cookie parameters
Callbacks and top-level webhooks as operations (use events)
Fetching a description from a URL on a hosted runtime

Importing a description proves nothing about your account with that provider. Credentials are checked only when an operation runs.

Read, change, reconcile

1 · Import

POST /v1/connections
{"family": "http_openapi", "name": "Asset Ledger",
 "config": {"base_url": "https://api.example.com", "openapi": "<document text>"},
 "credential": {"kind": "bearer", "value": "<api token>"}}

2 · Read the exact revision

POST /v1/capabilities/<getAsset id>/invoke  {"arguments": {"path": {"asset_id": "a-100"}}}

"target_revision": "\"1\""

3 · Apply one version-bound change
```
POST /v1/capabilities/<updateAsset id>/invoke
{"arguments": {"path": {"asset_id": "a-100"}, "body": {"location": "Bay 9"}},
 "idempotency_key": "move-a100-0001", "expected_revision": "\"1\""}
```
Operations that declare If-Match or x-ardyn-revision require expected_revision. Ardyn sends it in that header, with your Idempotency-Key. A stale revision fails at the target with no change.
4 · If the response is lost
```
"state": "outcome_unknown"
```
```
POST /v1/operations/<operation id>/reconcile
{"read_capability_id": "<getAsset id>", "arguments": {"path": {"asset_id": "a-100"}}}
```
```
{"applied": true, "write_resent": false, "operation": {"state": "reconciled", …}}
```
Repeating the same idempotency key returns the existing operation. A second request is never sent. Reconciliation adds a successor receipt and keeps the original “unknown” record. In acceptance, the target recorded exactly one change.