> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wiremock.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Import & Export - Via the API

> Automating import and export of mock API stubs via WireMock Cloud's API.

A mock API's stubs can be exported in bulk via the admin API. This can be useful for backing
up your API to source control, or cloning the contents of one API into another.

## Importing

To import any of the supported formats (Swagger, OpenAPI, WireMock Cloud WireMock JSON),
execute a `POST` request to the stub import URL e.g.:

<CodeGroup dropdown>
  ```bash theme={null}
  curl -v \
    --data-binary @my-swagger-spec.yaml \
    -H 'Authorization:Token my-api-token' \
    https://my-api.wiremockapi.cloud/__admin/ext/imports
  ```

  ```java theme={null}
  HttpResponse<String> response =
    Unirest.post("https://my-api.wiremockapi.cloud/__admin/ext/imports")
      .header("Authorization", "Token my-api-token")
      .body(Files.readAllBytes(Paths.get("my-swagger-spec.yaml")))
      .asString();
  ```

  ```javascript theme={null}
  const fs = require('fs');

  const options = {
    method: 'POST',
    headers: { 'Authorization': 'Token my-api-token' },
    body: fs.readFileSync('my-swagger-spec.yaml', 'utf8')
  };

  fetch('https://my-api.wiremockapi.cloud/__admin/ext/imports', options)
    .then(res => ...);
  ```

  ```python theme={null}
  import requests

  with open('my-swagger-spec.yaml', 'rb') as spec:
      response = requests.post(
          'https://my-api.wiremockapi.cloud/__admin/ext/imports',
          headers={'Authorization': 'Token my-api-token'},
          data=spec
      )
  ```

  ```ruby theme={null}
  require 'uri'
  require 'net/http'

  uri = URI('https://my-api.wiremockapi.cloud/__admin/ext/imports')

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Token my-api-token'
  request.body = File.read('my-swagger-spec.yaml')

  response = http.request(request)
  ```

  ```php theme={null}
  <?php
  $curl = curl_init('https://my-api.wiremockapi.cloud/__admin/ext/imports');

  curl_setopt_array($curl, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_POSTFIELDS => file_get_contents('my-swagger-spec.yaml'),
      CURLOPT_HTTPHEADER => [
          'Authorization: Token my-api-token',
      ],
  ]);

  $response = curl_exec($curl);
  ```

  ```go theme={null}
  import (
      "net/http"
      "os"
  )

  file, _ := os.Open("my-swagger-spec.yaml")
  defer file.Close()

  req, _ := http.NewRequest(
      "POST",
      "https://my-api.wiremockapi.cloud/__admin/ext/imports",
      file,
  )
  req.Header.Set("Authorization", "Token my-api-token")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  ```
</CodeGroup>

More detail can be found in our [API reference](../api-reference/imports/import-into-a-mock-api).

### Asynchronous imports

Larger imports can take a while to process, so every import runs as a background job.

When you call the import endpoint it will wait up to a configurable *sync timeout*
(3 seconds by default) for the import to finish:

* If the import finishes within the timeout, a `200` is returned containing the import
  result directly i.e. the IDs of the stub mappings created.
* If the import is still running when the timeout elapses, a `202 Accepted` response is
  returned containing details of the running job:

```json theme={null}
{
  "job": {
    "id": "8e2f3641-5f0a-45a2-9d1b-39cf16b2d0e7",
    "jobType": "multi-import",
    "status": "RUNNING",
    "started": "2024-09-05T10:20:46.143759190Z",
    "links": {
      "self": "/__admin/ext/jobs/8e2f3641-5f0a-45a2-9d1b-39cf16b2d0e7"
    }
  }
}
```

You can poll the job by sending a `GET` request to the URL in the job's `links.self`:

```bash theme={null}
curl -v \
  -H 'Authorization:Token my-api-token' \
  https://my-api.wiremockapi.cloud/__admin/ext/jobs/8e2f3641-5f0a-45a2-9d1b-39cf16b2d0e7
```

When the import finishes, the job's `status` will become `COMPLETE`, and its `outcome`
will contain the import result:

```json theme={null}
{
  "job": {
    "id": "8e2f3641-5f0a-45a2-9d1b-39cf16b2d0e7",
    "jobType": "multi-import",
    "status": "COMPLETE",
    "started": "2024-09-05T10:20:46.143759190Z",
    "finished": "2024-09-05T10:21:02.200386224Z",
    "elapsed": "PT16.056627034S",
    "links": {
      "self": "/__admin/ext/jobs/8e2f3641-5f0a-45a2-9d1b-39cf16b2d0e7"
    },
    "outcome": {
      "mappings": [
        {
          "id": "7e6d6733-881e-416d-9f6c-bad8d5015d0f"
        },
        {
          "id": "2791b6fe-bbbe-4102-a3fd-721fb9ba1557"
        }
      ]
    }
  }
}
```

If the import fails, the job's `status` will become `ERROR`, and its `outcome` will
contain the errors.

Note that if you're using the `api.wiremock.cloud` endpoint instead of your mock API's own
domain, the returned `links.self` URL will be of the form
`/v1/mock-apis/{mockApiId}/jobs/{jobId}`, but the behaviour is otherwise identical.

### Setting the sync timeout

The sync timeout can be changed - or disabled entirely - by supplying an import config in
a `config` part of a multipart request, with the `syncTimeout` set to an
[ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations):

```bash theme={null}
curl -v \
  -F 'file=@my-swagger-spec.yaml' \
  -F 'config={"import": {"syncTimeout": "PT10S"}};type=application/json' \
  -H 'Authorization:Token my-api-token' \
  https://my-api.wiremockapi.cloud/__admin/ext/imports
```

Setting `syncTimeout` to `PT0S` will disable waiting entirely - the endpoint will return
a `202` immediately, and you can poll the job for the result. Other import config options
such as `duplicatePolicy` can be supplied in the same `config` part.

More detail can be found in our [API reference](../api-reference/imports/import-into-a-mock-api)
and the [job status API reference](../api-reference/jobs/get-job-by-id).

## Exporting in WireMock Cloud/WireMock JSON format

To export an API's stubs, execute a `GET` request to the stub mappings admin URL e.g.:

<CodeGroup dropdown>
  ```bash theme={null}
  curl --output my-stubs.json \
    -H 'Authorization:Token my-api-token' \
    https://my-api.wiremockapi.cloud/__admin/mappings
  ```

  ```java theme={null}
  HttpResponse<String> response =
    Unirest.get("https://my-api.wiremockapi.cloud/__admin/mappings")
      .header("Authorization", "Token my-api-token")
      .asString();

  Files.writeString(Paths.get("my-stubs.json"), response.getBody());
  ```

  ```javascript theme={null}
  const fs = require('fs');

  const options = {
    headers: { 'Authorization': 'Token my-api-token' }
  };

  fetch('https://my-api.wiremockapi.cloud/__admin/mappings', options)
    .then(res => res.json())
    .then(json => fs.writeFileSync('my-stubs.json', JSON.stringify(json)));
  ```

  ```python theme={null}
  import requests

  response = requests.get(
      'https://my-api.wiremockapi.cloud/__admin/mappings',
      headers={'Authorization': 'Token my-api-token'}
  )

  with open('my-stubs.json', 'w') as stubs:
      stubs.write(response.text)
  ```

  ```ruby theme={null}
  require 'uri'
  require 'net/http'

  uri = URI('https://my-api.wiremockapi.cloud/__admin/mappings')

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = 'Token my-api-token'

  response = http.request(request)

  File.write('my-stubs.json', response.body)
  ```

  ```php theme={null}
  <?php
  $curl = curl_init('https://my-api.wiremockapi.cloud/__admin/mappings');

  curl_setopt_array($curl, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Token my-api-token',
      ],
  ]);

  $response = curl_exec($curl);

  file_put_contents('my-stubs.json', $response);
  ```

  ```go theme={null}
  import (
      "io"
      "net/http"
      "os"
  )

  req, _ := http.NewRequest(
      "GET",
      "https://my-api.wiremockapi.cloud/__admin/mappings",
      nil,
  )
  req.Header.Set("Authorization", "Token my-api-token")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  file, _ := os.Create("my-stubs.json")
  defer file.Close()
  io.Copy(file, resp.Body)
  ```
</CodeGroup>

You can find your API token at [https://app.wiremock.cloud/account/security](https://app.wiremock.cloud/account/security).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.