canonical: https://jentic.com/apis/apimatic.io/apimatic

# APIMATIC API Transformer

APIMATIC API Transformer is a single-endpoint service that converts API description files between formats such as OpenAPI, Swagger 2.0, RAML, API Blueprint, WSDL, Postman Collection, and APIMATIC's own format. The /transform endpoint accepts an input format identifier and the source file body, then returns the converted description. It is widely used in CI pipelines that need to keep multiple API description formats in sync from one canonical source. Authentication is by APIMATIC API key in the request or by HTTP basic credentials.

## For AI agents

Convert an API description from one format to another (OpenAPI, Swagger 2.0, RAML, API Blueprint, WSDL, Postman Collection) through one /transform call.

## Scope

Does not host specs, generate SDKs, or run linting - use for one-shot conversion between API description formats only.

## Capabilities

- Convert a Swagger 2.0 description into OpenAPI 3.0 in one POST /transform call
- Translate a RAML 1.0 file to OpenAPI 3.0 for tooling that does not read RAML
- Generate an OpenAPI description from a Postman Collection so it can be imported into spec-first tools
- Output an APIMATIC-formatted description suitable for SDK generation downstream
- Convert WSDL into OpenAPI to bring legacy SOAP endpoints into a REST-style catalog
- Round-trip an API description between formats inside a CI step to keep alternates in sync

## Use cases

### Spec format normalisation in CI

Run POST /transform as a CI step so that pushing a single canonical description automatically produces alternative formats for downstream consumers. Teams can keep an OpenAPI 3.0 source of truth and emit Postman, RAML, or APIMATIC descriptions with one HTTP call per target. This avoids drift between the canonical spec and the formats published to partners or developers.

Example prompt: POST /transform with input_format=APIMATIC, output_format=OpenApi3Json, and the canonical APIMATIC file as the body.

### Migrating from Swagger 2.0 to OpenAPI 3.0

Migrate legacy Swagger 2.0 files to OpenAPI 3.0 in bulk by scripting the /transform endpoint over a directory of specs. The conversion handles structural differences such as parameters, requestBody, and components so engineering teams do not need to rewrite every spec by hand. The output is a clean OpenAPI 3.0 document ready to lint, render, and host.

Example prompt: POST /transform with input_format=Swagger20, output_format=OpenApi3Json, and the legacy file body, then save the response as the new spec.

### Generating Postman Collections from OpenAPI

Produce an up-to-date Postman Collection from an OpenAPI 3.0 source as part of every release so QA engineers always test against the latest contract. /transform accepts OpenApi3Json or OpenApi3Yaml as input and emits Postman_2.1 as output. The result can be imported into a shared Postman workspace or attached to a release artefact.

Example prompt: POST /transform with input_format=OpenApi3Json, output_format=Postman_2.1, and the current spec, then upload the resulting collection to Postman.

### Agent-driven format conversion

An agent integrating with a partner that only accepts a specific description format can transform whatever the user provides into that format on the fly through Jentic. The conversion is one call, the credentials sit in your Jentic One instance, and the agent only needs to know which input and output formats are required. This removes a common friction point in agent-driven onboarding flows.

Example prompt: Through Jentic, search 'convert an API description format', load the apimatic.io /transform operation, and execute with input and output formats and the source file.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/transform` | Convert an API description from one format to another |

## Key resources

- **Transformer** — Single /transform endpoint that converts API description files between supported formats.

## Why Jentic

- **Setup:** Wiring the APIMATIC API Transformer by hand means setting up its API key or basic auth, packaging the source description, and handling the converted output yourself. Through Jentic you install once, import APIMATIC Transformer from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** The APIMATIC Transformer exposes a single transform operation that takes the source and target formats in the request, so scope the agent to that one operation. You choose the allowed operations, so the agent only calls what you list.
- **Credential handling:** Your APIMATIC credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'convert an API description to another format', and Jentic returns the matching APIMATIC Transformer operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **SwaggerHub API** — SmartBear platform that hosts and validates API specs in multiple formats.
- **Stoplight** — Spec-first design and docs hub with format support.
- **GitHub API** — Source-control surface where spec files live before conversion.

## FAQ

### What authentication does the APIMATIC API Transformer use?

The API supports two schemes: an apiKey credential and HTTP basic auth. Use whichever your APIMATIC plan provides. When called through Jentic, the chosen credential is held in your Jentic One instance and applied to the request server-side.

### Which input and output formats does /transform support?

The Transformer covers OpenAPI 3.0 (JSON and YAML), Swagger 2.0, Swagger 1.x, RAML 0.8 and 1.0, API Blueprint, WSDL, Postman Collection 1.0/2.0/2.1, and APIMATIC's own format. Pass the input_format and output_format identifiers in the request and the source as the body.

### Can I convert OpenAPI 3.0 into a Postman Collection?

Yes. POST /transform with input_format=OpenApi3Json (or OpenApi3Yaml) and output_format=Postman_2.1, and supply the source spec as the body. The response is a Postman Collection 2.1 file.

### How do I run a format conversion through Jentic?

Search Jentic for 'convert an API description format', load the apimatic.io /transform operation, and execute with input_format, output_format, and the source spec contents. Jentic returns the converted description without exposing the API key to the agent.

### What are the rate limits for the API Transformer?

Rate limits are not declared in the OpenAPI spec and depend on your APIMATIC plan tier. Treat HTTP 429 responses as a back-off signal and check the APIMATIC dashboard for current quotas.

### Can I limit what my agent is allowed to do with the APIMATIC API Transformer?

Yes. The APIMATIC Transformer exposes a single POST /transform operation that converts a source description between formats, and because Jentic One runs self-hosted under your control, your own rules decide which operations and credentials the agent may use. Since there is only the one transform call, you can scope the agent to that operation alone, so it can convert specs but nothing else. The APIMATIC API key or basic credential stays in your Jentic One instance and is applied server-side, so the agent never sees it and can only invoke the operations you have listed.