Skip to main content

Start a Pipeline

Overview​

In this guide we will show you how to start a pipeline via API Key.

Prerequisites​

  • apiKey: The API Key of the pipeline you want to start. (Get Pipeline API Key)
  • pipelineId: The ID of the pipeline you want to start.

Request​

Endpoint​

Make a POST request to the following endpoint: 

https://api.pupau.ai/pipelines/:pipelineId/queries?sse=true
  • sse: a boolean that indicates if the response should be streamed. Can be omitted (default is false). To know more about SSE: Wikipedia

Request Headers​

Api-Key: <apiKey>

Request Body​

Pipeline can be started with a body where you can specify the request and the context or a file in FormData format.

To start a pipeline with a body you can use the following body:

{
    "request": "Tell me about the history of the world",
    "context": "The history of the world is a long and complex story, but it can be summarized in a few key points."
}
  • request: The request to send to the pipeline.
  • context: The context to send to the pipeline, useful to improve the response.

To start a pipeline with a file you can use the following format:

"file": your_file
  • file: The file you want to upload. Must be in FormData format.

Response SSE​

If you set the sse parameter to true, you will receive a stream of "data" JSON objects.
Here is an example of the stream:

data: {"type":"LAYER_MESSAGE","message":"Executing layer 0...","layerId":"0","executionCount":1}
data: {"type":"STREAMING_RESPONSE","actorId":"actor-1","message":"Hel","layerId":"0"}	
data: {"type":"STREAMING_RESPONSE","actorId":"actor-1","message":"lo!","finished": true,"layerId":"0"}	
data: {"type":"LAYER_RESPONSE","layerId":"0","responses":[{"actorId":"actor-1","message":"Hello!","errors":[],"info":[]}]}	
data: {"type":"LAYER_MESSAGE","message":"Executing layer 1...","layerId":"1","executionCount":1}
data: {"type":"STREAMING_RESPONSE","actorId":"actor-2","message":"Hi", "lastLayer": true,"layerId":"1"}	
data: {"type":"STREAMING_RESPONSE","actorId":"actor-2","message":"John!","finished": true,"layerId":"1"}	
data: {"type":"STREAMING_RESPONSE","actorId":"actor-3","message":"Greetings!","finished": true,"layerId":"1"}
data: {"type":"LAYER_RESPONSE","layerId":"1","responses":[{"actorId":"actor-2","message":"Hi John!","errors":[],"info":[]},{"actorId":"actor-3","message":"Greetings!","errors":[],"info":[]}], "last": true}

Here is an example of a LAYER_RESPONSE with an error:

{"type":"LAYER_RESPONSE","layerId":"0","responses":[{"actorId":"document-converter","message":"Error during PDF processing.","info":[],"errors":[{"message":"Invalid PDF structure.","name":"InvalidPDFException"}]}],"executionCount":1,"last":true}

Each type represents a different event in the pipeline execution:

  • LAYER_MESSAGE: indicates the layer has started executing.
  • STREAMING_RESPONSE: indicates a streaming response from an actor.
  • LAYER_RESPONSE: indicates that the layer has finished the execution.

When an actor has finished elaborating the request, the finished property will be set to true. This cycle will repeat until all layers have finished the execution. The last layer will have the last property set to true.

Response REST​

If you set the sse parameter to false, you will receive a JSON object
Here is an example of the response:

[
    {
        "actorId": "actor-1",
        "message": "Hello!",
        "info": [],
        "errors": []
    },
    {
        "actorId": "actor-2",
        "message": "Hi John!",
        "info": [],
        "errors": []
    }
]