HTTP Entry Point
By default, every application is accessible through HTTP calls and the Seaplane
CLI. Read more about the specifics of calling your REST-enabled application,
directly with a cURL request or the CLI in the sections below.
HTTP calls enable you to trigger runs and retrieve data from pipelines from any
other platform. The POST and GET endpoints follow the following structure.
Based on the application name you provided to your app instance i.e.,
App('application-name')
POST: https://carrier.cplane.cloud/v1/endpoints/<application-name>/request
GET: https://carrier.cplane.cloud/v1/endpoints/<application-name>/response/<request_id>/archive?pattern=.>&format=json_array
POST Request​
To trigger a run of your application call the POST endpoint with a cURL
request or through the Seaplane CLI as follows. When successful the POST request
returns a request ID which can be used to retrieve the output using a GET
request.
- cURL
- CLI
curl -X POST -H 'Content-Type: application/octet-stream' \
--header "Authorization: Bearer $(curl https://flightdeck.cplane.cloud/identity/token --request POST --header "Authorization: Bearer <YOUR-API-KEY>")" \
-d '{"hello": "world"}' https://carrier.cplane.cloud/v1/endpoints/<APPLICATION-NAME>/request
Add data to your post request as binary data through the -d flag. This allows
you to add a variety of data objects such as JSON strings, files, or any other
binary data format. Make sure to mark your Content-Type as octet-stream.
For example, you can add a PDF file to your POST request as follows.
curl -X POST -H 'Content-Type: application/octet-stream' \
--header "Authorization: Bearer $(curl https://flightdeck.cplane.cloud/identity/token --request POST --header "Authorization: Bearer <YOUR-API-KEY>")" \
-d @my-pdf.pdf https://carrier.cplane.cloud/v1/endpoints/<APPLICATION-NAME>/request
Replace <YOUR-API-KEY> with your API key and <APPLICATION-NAME> with your
application name.
Expected Output:
{ "request_id": "036cf50b-d81d-4312-a860-382202dcdbfa" }
You can trigger a run of a pipeline directly using the Seaplane CLI. Triggering a run with the Seaplane CLI only works when you are in the root directory of your application.
Add data to your request as binary data through the -d flag. This allows you
to add a variety of data such as JSON strings, files, or any other binary data
format.
seaplane request -d '{"hello" : "world"}'
For example, you can add a PDF file to your POST request as follows.
seaplane request -d @my-pdf.pdf
Expected Output:
request_id: 8e1672a2-4ae1-4d1f-b2a4-b509f3b3409f
The input data of a POST request is very flexible. For example, you can send
JSON strings, PDF files or any other binary data format. As a result, you are in
charge of handling the input data inside your app correctly. You can learn more
about handling input data in the task message section of
our documentation.
GET Request​
Seaplane supports requesting data from the application through a GET request
to the application URL or directly using the Seaplane CLI. Use the request_id
output from a POST request or CLI command to request the associated response.
- cURL
- CLI
curl -X GET --header "Authorization: Bearer $(curl https://flightdeck.cplane.cloud/identity/token --request POST --header "Authorization: Bearer <YOUR-API-KEY>")" \
"https://carrier.cplane.cloud/v1/endpoints/<APPLICATION-NAME>/response/<REQUEST-ID>/archive?pattern=.>&format=json_array"
Replace <APPLICATION-NAME> with your application name, <YOUR-API-KEY> with
your API key, and <REQUEST-id> with your request ID.
Expected Output:
The output bytes object as defined in your application through
app.respond(my_output_data)
You can request output data from your pipeline directly using the Seaplane CLI. Requesting output data through the CLI only works when you are in the root directory of your application.
seaplane response
By default seaplane response returns the output from your latest request, you
can override this by supplying it with a specific request ID using the -r or
--request_id flag as follows.
seaplane response --request_id <REQUEST-ID>
Replace <REQUEST-ID> with your request ID.
Expected Output:
The output bytes object as defined in your application through
app.respond(my_output_data)