Skip to main content

Generate a Portal using the Async API

Step 1: Initiate Portal Generation​

Use the APIMatic API to invoke the Generate On-Prem Portal via Build Input Async endpoint. Provide the required Build Input in your request. For details on preparing the Build Input, refer to this guide. A successful request returns a response containing an id and links to check the status and download the portal.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "id": "0194caa0-d38a-72e9-bcc8-df71acb5fd97",
  "links": {
    "status": "https://api.apimatic.io/portal/v2/0194caa0-d38a-72e9-bcc8-df71acb5fd97/status",
    "download": "https://api.apimatic.io/portal/v2/0194caa0-d38a-72e9-bcc8-df71acb5fd97/download"
  }
}

Step 2: Monitor Generation Status​

Poll the status endpoint periodically to check the portal generation progress.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "InProgress"
}

Step 3: Download the Generated Portal​

Once generation is complete, the status endpoint responds with a 302 Redirect to the download endpoint. The download endpoint provides a ZIP file containing the portal artifacts.

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="portal.zip"
Content-Length: 123456

[Binary data not displayed]

Step 4: Host the API Portal​

  1. Extract and host the generated portal on any web server. You can preview it locally using http-server or similar tools.

Host API Portal

Alternative: Using a Callback URL

As an alternative to polling the status endpoint to monitor progress, you can configure a callback URL to receive a notification when your portal generation completes.

Step 1: Send a Request with a Callback URL​

Pass the X-APIMatic-CallbackUrl header in your request to the async API. When the portal is ready, APIMatic will send a request to the provided URL with the generation status and download link.

Sample Callback Request Body​

{
  "id": "0194caac-2a02-799f-a3ef-4d6aee48df1a",
  "status": "GenerationCompleted",
  "link": "https://api.apimatic.io/portal/v2/0194caac-2a02-799f-a3ef-4d6aee48df1a/download"
}

This approach eliminates the need for polling and ensures automatic notification once portal generation is complete.

To automate the entire docs as code process, go to the Automate API Portal Generation using the Async API.