The Xribe runtime RESTful API can be used to create HTML and PDF output from Web Designer templates, get up-to-date information about your output generation requests and manage your webhooks.

The base URL for the Xribe runtime RESTful API is https://runtime.compose.platform.unifiedpost.com/api

There are two typical scenarios for generating output with the Xribe runtime API. Both scenarios start with a POST request to v1/message to initiate an output generation request, which will return a message ID that identifies this request.

In the preferred scenario Xribe will call the configured webhook when the output is generated:

                    +---------+              +-------+
                    | Client  |              | Xribe |
                    +---------+              +-------+
                          |                       |
                          | Add a new message     |
                          |---------------------->|
                          |                       | -------------------\
                          |                       |-| Validate request |
                          |                       | |------------------|
                          |                       |
                          |            message ID |
                          |<----------------------|
                          |                       | ---------------------\
                          |                       |-| Create deliverable |
                          |                       | | Generate output    |
                          |                       | |--------------------|
                          |      Webhook Callback |
                          |<----------------------|
      ------------------\ |                       |
      | Accept callback |-|                       |
      |-----------------| |                       |
                          |                       |
                          | respond with 2xx      |
                          |---------------------->|
------------------------\ |                       |
| Handle callback async |-|                       |
|-----------------------| |                       |
                          |                       |
                          | Retrieve output       |
                          |---------------------->|
                          |                       |

In the second scenario Xribe will not call a webhook when the output is generated, but the Client will use polling to see when the output is ready.:

                              +---------+                           +-------+
                              | Client  |                           | Xribe |
                              +---------+                           +-------+
                                    |                                    |
                                    | Add a new message                  |
                                    |----------------------------------->|
                                    |                                    | -------------------\
                                    |                                    |-| Validate request |
                                    |                                    | |------------------|
                                    |                                    |
                                    |                         Message ID |
                                    |<-----------------------------------|
                                    |                                    |
                                    | Get message info (deliverable ID)  |
                                    |----------------------------------->|
                                    |                                    |
                                    |      Message info (deliverable ID) |
                                    |<-----------------------------------|
----------------------------------\ |                                    |
| Repeat until deliverable exists |-|                                    |
|---------------------------------| |                                    | -----------------------\
                                    |                                    |-| Create delivererable |
                                    |                                    | |----------------------|
                                    | Get deliverable info (status)      |
                                    |----------------------------------->|
                                    |                                    |
                                    |          Deliverable info (status) |
                                    |<-----------------------------------|
                                    |                                    | ------------------\
                                    |                                    |-| Generate output |
                                    |                                    | |-----------------|
                                    |                                    |
                                    | Get deliverable info (status)      |
                                    |----------------------------------->|
                                    |                                    |
                                    |          Deliverable info (status) |
                                    |<-----------------------------------|
----------------------------------\ |                                    |
| Repeat until status 'generated' |-|                                    |
|---------------------------------| |                                    |
                                    |                                    |
                                    | Get deliverable info               |
                                    |----------------------------------->|
                                    |                                    |
                                    |                   Deliverable info |
                                    |<-----------------------------------|
                                    |                                    |
                                    | Retrieve output                    |
                                    |----------------------------------->|
                                    |                                    |

All requests to the Xribe Runtime API must be authenticated. See OAuth 2.0 for information on how to obtain security tokens and Performing authenticated requests on how to use them.

The Xribe Runtime API uses https://login.inventivedesigners.com as its authentication and authorization server.

OAuth tokens are valid for 10 minutes by default. Reuse the token across requests to save on OAuth requests.

Users that make calls to the Xribe Runtime API should have permission output-center. In addition to this they should also have access to the different resources.

When Xribe handles a message, it provisions and manages the resources needed to execute output generation and delivery. When output generation is requested, Xribe launches an execution context to perform this operation. The execution context is a temporary runtime environment that uses your provided template to generate output. It takes some time to set up an execution context and do the necessary "bootstrapping". Every time an execution context needs to be constructed, some additional latency may be noticable.

After a message request is handled, Xribe maintains the execution context for some time in anticipation of additional output generation requests. This facilitates improved performance for subsequent requests as there is no need to set up the output generation again. Since Xribe reuses previously created execution contexts, keep the following implication in mind: any modifications made by javascript code that may be embedded in the template, persist and exist for the lifecycle of the execution environment. Consider, for instance, a situation where a fresh execution environment is started and an incoming request is processed. Say some javascript code that changes an environment variable is embedded in the template and is executed. Then any future requests that will be handled by the same execution environment, will be using the updated environment variable that was changed by the first request. Caution is advised to only deploy vetted code that sanitizes any uncontrolled input data.

Execution contexts are solely shared between requests for the same project and environment. They are never shared across environment, project or tenant borders.

When Xribe receives a message of type documentflow, it provisions a process server with the specified package deployed to handle the message. Multiple instances can be started depending on the load, and a single instance can process multiple messages. The started instances are temporary environments, local storage will be deleted when the instance is recycled. If persistent storage is required, use the temporary location provided by the initial step, or use the temporary data steps. Temporary data is automatically deleted after three months.

Note that instances can be terminated at any time, after wich the message will be offered to a new instance. Make sure the defined flows and processes can handle sudden termination and the subsequent reprocessing of a message. When a document flow instance succesfully completes, the message will be considered processed.

Execution contexts are solely shared between requests for the same project, environment and package. They are never shared across package, environment, project or tenant borders.

Xribe will deliver webhook notifications as soon as possible after the requested output was generated.

Webhook applications must respond within 10 seconds with an HTTP 2xx response code to acknowledge the notification. Failure to respond within 10 seconds or returning a different status code will trigger a retry attempt.

Unsuccessful Webhook notifications are retried for up to 72 hours. After 72 hours have elapsed, the notification is discarded and will not be sent again. Xribe uses a backoff mechanism to avoid flooding webhook applications with retry attempts (exponential backoff with a one hour maximum between attempts). Notifications are retried according to the following schedule:

⚠️ Warning: endpoints from ngrok, i.e. endpoints containing ".ngrok-free.app" will only be retried twice.

Your account has service limits assigned to it. These limits are in place to protect users of the service by preventing unintentional high usage or malicious activities to rack up very high consumption bills. Additionally, the limits also protect the integrity of the service. Hitting these limits can result in throttling (for example HTTP response 429 "Too Many Requests"). Most of these limits are soft limits. Different usage plans with higher limits can be assigned to your account on request.

Composition

The most important addition to version 1 of the API is the ability to pass in and compose multiple inputs. This means that when creating a message request you can pass in an array of inputs. You can compose these different inputs by specifying a compose script that describes how to combine the different inputs. Note that this requires each input to have an ID from now on. Allowing multiple inputs also has some consequences for the deliverable since you can now have distinct outputs. As a consequence, properties such as the page count and output properties have moved to the respective output in the deliverable. For more detailed information and help migrating from an earlier version to version 1, have a look at our Migration Guide.

For more information about compose scripts and the supported operations, see Composition Guide.

Example of a compose output request:

{
  "projectID": "96dd5fcf-e20a-43b4-a9b9-705347f5f19f",
  "environmentID": "37b2f370-81e2-47ff-9396-d3f60d7c27e7",
  "properties": {
    "description": "Letter - Insurance Claim"
  },
  "outputParameters": {
    "type": "pdf",
    "profile": "PDF/X-4"
  },
  "deliveryParameters": {
    "webhookParameters": {
      "generated": {
        "endpoint": "https://grok.io/callback",
        "authorizationHeader": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFU"
      }
    }
  },
  "input": [
    {
      "id": "letter",
      "type": "template",
      "ref": "letter.sdt",
      "theme": "themes/rialto-bank.html",
      "data": {
        "amount": 250000,
        "rate": 2.5
      }
    },
    {
      "id": "overlay",
      "type": "resolve",
      "ref": "logo.pdf"
    }
  ],
  "compose": {
    "ref": "overlay.json"
  }
}

Document Flow service

Version 1 of the API has also been extended with support for submitting messages to trigger cloud-deployed Design & Compose Document Flow instances. Such cloud-deployed Document Flows need to meet certain requirements and have some limitations compared to regular Document Flows deployed in on-premise environments. See Document Flow Service for more information on Document Flow design specific for the Xribe Runtime.

The Xribe Runtime API itself also has certain limitations when submitting messages intended to trigger a Document Flow instance. When submitting Document Flow messages, only a single input (of type documentflow) is supported and post-processing in the form of a Composition script is not allowed. Also, messages intended for Document Flow should contain only inline JSON data; remote data in the form of a URL is not supported. If remote data is to be passed on to a Document Flow instance, it should be wrapped in a JSON object that is passed inline with the message request. It is then up to the receiving Document Flow instance to interpret this URL and retrieve the data. Do take note that Document Flow messages might take some time before they are processed; care should be taken that any URLs passed to a Document Flow instance remain valid for a sufficient period of time. Finally, the entire Document Flow message request should be small in size (less than 2 KiB).

When you are making requests at a higher rate than your usage plan allows, an HTTP status code of 429 ("Too Many Requests") will be returned. In this case you can safely retry this call, but you should lower the rate at which you are sending requests.

While our service is scaling, it is possible an HTTP status code of 500 ("Internal Server Error") or 504 ("Gateway Timeout") might be returned rather than a 429. After a couple of seconds our service will have scaled up and you can restart sending requests, which will be successfully handled again.

Get information about messages. A message will result in a deliverable with one or more outputs.

Get information about deliverables. A deliverable is the result of a message and contains one or more outputs.