# Configuration

Read the rest of your organization's setup: connections, envelopes, webhooks, flows, mappings, implementations and sources. Together with the Partners endpoints these let your code, or a coding agent, walk from a failed transaction to its partner, to the transaction set setting, to the mapping, to the implementation, to the JSON schema the mapping targets, with no guessing at any step.

**Preview.** These endpoints are in preview, like the [Partners](/resources/api-docs/partners) endpoints. Their response shapes may change without notice while the configuration model settles. Do not pin anything critical to them yet.

Every endpoint here is read-only and follows the pattern the Partners page sets: compact list rows, a show that embeds related objects with their ids, raw facts rather than computed verdicts, the shared cursor pagination, no secrets ever, and a standard API key required. Sandbox keys are refused.

Ids are the identifiers. Every `get` takes an id; a partner key is a list filter, never a path segment here. Each resource that points at another returns it as `{ "id", "name" }`, or `{ "id", "key", "name" }` for a partner, and each resource lists what points at it.

## Not found

Every show answers an unknown or malformed id with the same shape, and `reason` names the resource so a caller can tell it from a wrong base path:

```json
{
  "error": {
    "message": "No mapping found with id 6e0c...",
    "code": "not_found",
    "reason": "mapping"
  }
}
```

The reasons are `connection`, `envelope`, `webhook`, `flow`, `mapping`, `mapping_version`, `implementation` and `source`.

## Connections

```
GET /platform/connections
GET /platform/connections/:id
```

A list row carries `id`, `name`, `kind` (`sftp`, `as2` or `sandbox`), `host`, `provisioned`, `as2Ready` and `partnerCount`. The show is the connection shape a partner embeds (transport settings, directories, AS2 identifiers and setup status, tags) plus `partners`, the partners assigned to it:

```json
{
  "id": "a1b2c3d4-...",
  "name": "Acme SFTP",
  "kind": "sftp",
  "host": "sftp.acme.example",
  "port": 22,
  "username": "tediware",
  "inboundDirectory": "/out",
  "outboundDirectory": "/in",
  "provisioned": true,
  "as2Ready": false,
  "tags": [],
  "partners": [
    { "id": "8c2021f8-...", "key": "ACME", "name": "Acme Foods" }
  ],
  "createdAt": "2026-05-14T10:02:11.004Z",
  "updatedAt": "2026-08-29T16:41:52.118Z"
}
```

Passwords, passphrases and private keys are absent, not masked, whether or not the connection is provisioned.

## Envelopes

```
GET /platform/envelopes
GET /platform/envelopes/:id
```

A list row carries `id`, `name`, `external`, `interchangeExtid`, `interchangeExtidQualifier` and `applicationCode`. `external` is `true` for an envelope that identifies a trading partner and `false` for one that identifies you. The show adds the separators and `partners`, each with the `role` the envelope plays for that partner (`internal` or `external`), since one envelope can be your identity on one partner and, rarely, a partner's identity on another.

```json
{
  "id": "e1f2a3b4-...",
  "name": "Our identifiers",
  "external": false,
  "interchangeExtid": "YOURID",
  "interchangeExtidQualifier": "ZZ",
  "applicationCode": "YOURID",
  "segmentSeparator": "~",
  "elementSeparator": "*",
  "componentSeparator": ">",
  "partners": [
    { "id": "8c2021f8-...", "key": "ACME", "name": "Acme Foods", "role": "internal" }
  ],
  "createdAt": "2026-05-14T10:02:11.004Z",
  "updatedAt": "2026-05-14T10:02:11.004Z"
}
```

## Webhooks

```
GET /platform/webhooks
GET /platform/webhooks/:id
```

A list row carries `id`, `name`, `kind` (`standard` or `sandbox`) and `url`. The show adds `contentType` and `partners`, each with the `role` (`inbound`, `outbound` or `error`); a partner that uses one webhook for two roles appears twice. The signing secret, the sandbox sink token and the sandbox API key are never returned.

## Flows

```
GET /platform/flows
GET /platform/flows/:id
```

A list row:

```json
{
  "id": "f1b2c3d4-...",
  "name": "Acme Outbound",
  "direction": "outbound",
  "status": "active",
  "frequency": 5,
  "versionNumber": 3,
  "usesSandbox": false,
  "partner": { "id": "8c2021f8-...", "key": "ACME", "name": "Acme Foods" },
  "createdAt": "2026-05-14T10:02:11.004Z",
  "updatedAt": "2026-08-29T16:41:52.118Z"
}
```

`status` is `pending` or `active`, and only an active flow accepts traffic. `frequency` is the polling interval in minutes, `0` meaning paused. Only the current version of each flow is listed; rebuilding a flow supersedes the old version and it drops out of this list.

Filters: `partner` (a key, any case), `direction` (`inbound` or `outbound`) and `status`. An unknown partner key returns an empty page; a value outside the vocabulary is refused with `invalid_parameter`.

The show adds the graph, as node identities and edges, so the shape of a flow reads without the canvas:

```json
{
  "nodes": [
    { "id": "n1...", "name": "Partner endpoint", "kind": "input", "service": "partner_endpoint" },
    { "id": "n2...", "name": "Acme 856 mapping", "kind": "transformation", "service": "mapping" },
    { "id": "n3...", "name": "Upload", "kind": "output", "service": "sftp_upload" }
  ],
  "connections": [
    { "from": "n1...", "to": "n2..." },
    { "from": "n2...", "to": "n3..." }
  ]
}
```

Node configuration is not returned. A node's connection, webhook, mapping or implementation is reached through that resource's own endpoint.

## Mappings

```
GET /platform/mappings
GET /platform/mappings/:id
GET /platform/mappings/:id/versions
GET /platform/mappings/:id/versions/:number
```

A list row:

```json
{
  "id": "m5b6c7d8-...",
  "name": "Acme 856",
  "direction": "outbound",
  "implementation": { "id": "i1b2c3d4-...", "name": "Acme 856 4010" },
  "source": { "id": "s1b2c3d4-...", "name": "Shipment" },
  "currentVersion": 4,
  "placeholderCount": 2,
  "partners": ["ACME"],
  "createdAt": "2026-05-14T10:02:11.004Z",
  "updatedAt": "2026-08-29T16:41:52.118Z"
}
```

Filters: `direction` and `partner` (a key). `partners` lists the keys of the partners whose transaction set settings use this mapping.

The show adds `description`, `tags`, the source embedded in full (its sample and semantics are what a reader of the transformation needs beside it) and `current`, the latest version:

```json
{
  "current": {
    "versionNumber": 4,
    "transformation": "{ \"shipment\": { ... } }",
    "placeholders": [
      { "value": "SCAC", "reason": "Carrier code not in source data", "position": 812, "line": 31, "column": 14 }
    ],
    "note": "Added carrier placeholder",
    "createdAt": "2026-08-29T16:41:52.118Z",
    "createdBy": { "name": "Dana Ortiz" }
  }
}
```

The implementation stays a reference; its schema comes from `GET /platform/implementations/:id/schema`. A mapping saved before versions existed has `current.versionNumber` `null` and the transformation as stored.

`versions` lists every version, oldest first, as `versionNumber`, `note`, `createdAt` and `createdBy`, in the pagination envelope under `versions`. `versions/:number` returns that version in the same shape as `current`.

```bash
curl "https://tediware.com/platform/mappings/m5b6c7d8-.../versions/3" \
  -H "Authorization: Key your-api-key-here"
```

## Implementations

```
GET /platform/implementations
GET /platform/implementations/:id
GET /platform/implementations/:id/schema
GET /platform/implementations/:id/guide?variant=console|markdown
GET /platform/implementations/:id/export
```

These cover your organization's own implementations only. Public implementations, the shared catalogue you copy from in the application, are not listed, fetched, rendered or exported through the API: a read over the catalogue would let one key walk it. Import the public one into your account in the app and it is yours from then on, with `sourceImplementation` recording where it came from.

A list row:

```json
{
  "id": "i1b2c3d4-...",
  "name": "Acme 856 4010",
  "version": "2",
  "status": "active",
  "transactionSet": { "identifier": "856", "release": "004010" },
  "sourceImplementation": { "id": "p1b2c3d4-...", "name": "Public 856 (ANSI 4010)" },
  "segmentUseCount": 42,
  "loopUseCount": 9,
  "createdAt": "2026-05-14T10:02:11.004Z",
  "updatedAt": "2026-08-29T16:41:52.118Z"
}
```

Filter: `transactionSetIdentifier`, a transaction set code such as `850`.

The show adds `description`, `tags`, `mappings` (the mappings that target it) and `partners` (the partners that use it directly, without a mapping). The structure itself is never inlined. It has three representations, because an implementation is three things to three readers:

- **`schema`** returns the JSON schema (draft 2020-12) of the shape a mapping targeting this implementation must produce. Outbound, that is the partner's document; inbound, it is the canonical shape you defined. Either way it is the shape to write a mapping against.
- **`guide`** returns the rendered guide as text: every table, loop, segment and element the implementation uses, with requirement, repeats, allowed codes, notes and conditions, and any deviations from the X12 standard. `variant=console` (the default) is the terminal rendering as `text/plain`; `variant=markdown` is the same content as `text/markdown`. The guide is presentation only, like the X12 reference pages; there is no JSON variant.
- **`export`** returns the whole implementation as one portable JSON document, keyed by segment codes, positions and loop identifiers rather than database ids, so it reads the same anywhere. Keep it in version control, diff two revisions of a partner specification, or attach it to a support conversation.

```bash
curl "https://tediware.com/platform/implementations/i1b2c3d4-.../schema" \
  -H "Authorization: Key your-api-key-here"

curl "https://tediware.com/platform/implementations/i1b2c3d4-.../guide?variant=markdown" \
  -H "Authorization: Key your-api-key-here"
```

## Sources

```
GET /platform/sources
GET /platform/sources/:id
```

A source is a representative sample of the JSON your system sends, with an optional semantics note describing its fields. It is example data rather than a schema, and every mapping is written against one. A list row carries `id`, `name` and `mappings` (the mappings that read from it); the show adds `sample` and `semantics`. The same shape is embedded on a mapping's show, so listing sources is how an agent finds the samples your organization already has before writing a mapping.

## Error Responses

```
| Status | Code              | Cause                                                                      |
|--------|-------------------|----------------------------------------------------------------------------|
| 400    | invalid_parameter | A filter, cursor or guide variant outside its vocabulary                   |
| 401    | unauthorized      | The API key is missing or invalid                                          |
| 403    | forbidden         | The key is a sandbox key. These endpoints cover the whole organization     |
| 404    | not_found         | No such resource in your organization; `reason` names the resource         |
```