---
sidebar_position: 1
---

# Call via API

Once deployed, your pipelines can be called with POST/GET requests.

:::tip Tip

If you've deployed Piper on your own server, replace **piper.my** with your domain name.

:::

## Run pipeline

```bash
curl --location --request POST 'https://app.piper.my/api/pipeline-slug/launch' \
--header 'content-type: application/json' \
--header 'api-token: [YOUR_API_KEY_HERE]' \
--data '{
  "inputs": {
    name: "Bob Marley",
    age: 36,
    died: true
  }
}'
```

:::tip Important

Input type could only primitive: `boolean` | `number` | `string` 

:::

Some pipelines accept JSON as input.

In this case, the JSON must still be serialized into a string.

```json
{
  "inputs": {
    "props": "{ \"name\": \"Bob Marley\", \"age\": 36 }"
  }
}
```

### Images & Media types

There are two ways to send images and other media like videos or audio:
1. JSON Base64: `data:image/jpeg;base64,...`
2. Uploading as an artefact.

#### JSON Base64

```bash
curl --location --request POST 'https://app.piper.my/api/pipeline-slug/launch' \
--header 'content-type: application/json' \
--header 'api-token: [YOUR_API_KEY_HERE]' \
--data '{
  "inputs": {
    image: "data:image/jpeg;base64,..."
  }
}'
```

:::danger Limits

For stability and performance reasons, JSON payloads are limited to 2048 KB.
For large media files, please upload them as artifacts.

:::

#### Uploading artefact

Piper has its own temporary storage for handling large media files.

```bash
curl --location --request POST 'https://app.piper.my/api/artefacts' \
--header 'api-token: [YOUR_API_KEY_HERE]' \
-F "file=@/path/to/your/file.jpg"
```

After the upload, you will receive a URL to access the file.

:::danger Limits

Your file will be deleted automatically after ~48 hours.

:::

## Pipeline status

```bash
curl --location --request GET 'https://app.piper.my/api/launches/[LAUNCH_ID]/state' \
--header 'api-token: [YOUR_API_KEY_HERE]'
```

Depending on the pipeline type, we recommend polling every 2–5 seconds.

Since outputs in a pipeline are set asynchronously, you need to wait for all the outputs you're expecting.

:::tip Question

> Do you support webhooks or streaming events?

**It's coming very soon!**

Please vote for the [related issue](https://github.com/my-piper/piper/issues/17) to show your support.

:::