---
title: "Create a new pipeline at a caller-supplied id"
---

> Documentation Index
> Fetch the complete documentation index at: https://www.arroyo.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new pipeline at a caller-supplied id

Path: Arroyo REST API › pipelines

`PUT /v1/pipelines/{id}`

URL: `http://localhost:5115/api/v1/pipelines/{id}`

The API will create a single job for the pipeline, using the
supplied `id`. Useful when an upstream system wants to address
the pipeline by an id it already manages.

The endpoint is currently create-only: PUTing twice with the same id
returns a 400 (duplicate-violation) rather than upserting.

## Path parameters

- `id` (`put_pipeline.path.id`; string, required) — Caller-supplied pipeline id

## Request body

_Required._

- `name` (`put_pipeline.name`; string, required)
- `parallelism` (`put_pipeline.parallelism`; integer, required)
  - format: `int64` · minimum: `0`
- `query` (`put_pipeline.query`; string, required)
- `checkpoint_interval_micros` (`put_pipeline.checkpoint_interval_micros`; integer, optional, nullable)
  - format: `int64` · minimum: `0`
- `env_vars` (`put_pipeline.env_vars`; map of string, optional, nullable) — Per-job environment variables forwarded to workers.
- `scheduler_config` (`put_pipeline.scheduler_config`; unknown, optional, nullable) — Per-job scheduler configuration overlay. The shape mirrors the controller's global scheduler config (e.g. the `kubernetes-scheduler.*` block) and is merged on top of it at scheduling time. An omitted field, `null`, or an empty object all mean "use the controller's global scheduler config unchanged".
- `state_url` (`put_pipeline.state_url`; string, optional, nullable)
- `tags` (`put_pipeline.tags`; map of string, optional, nullable)
- `udfs` (`put_pipeline.udfs`; array of object, optional, nullable)
  - `definition` (`put_pipeline.udfs.definition`; string, required)
  - `language` (`put_pipeline.udfs.language`; string, optional)
    - one of `"python"`, `"rust"`

## Example request

```json
{
  "checkpoint_interval_micros": 0,
  "env_vars": {
    "property1": "string",
    "property2": "string"
  },
  "name": "string",
  "parallelism": 0,
  "query": "string",
  "scheduler_config": null,
  "state_url": "string",
  "tags": {
    "property1": "string",
    "property2": "string"
  },
  "udfs": [
    {
      "definition": "string",
      "language": "python"
    }
  ]
}
```

## Code samples

### cURL

```bash
curl --request PUT \
  --url 'http://localhost:5115/api/v1/pipelines/<id>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "checkpoint_interval_micros": 0,
  "env_vars": {
    "property1": "string",
    "property2": "string"
  },
  "name": "string",
  "parallelism": 0,
  "query": "string",
  "scheduler_config": null,
  "state_url": "string",
  "tags": {
    "property1": "string",
    "property2": "string"
  },
  "udfs": [
    {
      "definition": "string",
      "language": "python"
    }
  ]
}
'
```

### TypeScript

```typescript
const url = 'http://localhost:5115/api/v1/pipelines/<id>';
const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    checkpoint_interval_micros: 0,
    env_vars: {property1: 'string', property2: 'string'},
    name: 'string',
    parallelism: 0,
    query: 'string',
    scheduler_config: null,
    state_url: 'string',
    tags: {property1: 'string', property2: 'string'},
    udfs: [{definition: 'string', language: 'python'}]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "http://localhost:5115/api/v1/pipelines/<id>"

payload = {
    "checkpoint_interval_micros": 0,
    "env_vars": {
        "property1": "string",
        "property2": "string"
    },
    "name": "string",
    "parallelism": 0,
    "query": "string",
    "scheduler_config": None,
    "state_url": "string",
    "tags": {
        "property1": "string",
        "property2": "string"
    },
    "udfs": [
        {
            "definition": "string",
            "language": "python"
        }
    ]
}
headers = {"Content-Type": "application/json"}

response = requests.put(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 200

Created pipeline and job

#### Example

```json
{
  "action": "none",
  "action_in_progress": true,
  "action_text": "string",
  "checkpoint_interval_micros": 0,
  "created_at": 0,
  "graph": {
    "edges": [
      {
        "dest_id": 0,
        "edge_type": "string",
        "key_type": "string",
        "src_id": 0,
        "value_type": "string"
      }
    ],
    "nodes": [
      {
        "description": "string",
        "node_id": 0,
        "operator": "string",
        "parallelism": 0
      }
    ]
  },
  "id": "string",
  "name": "string",
  "preview": true,
  "query": "string",
  "state_url": "string",
  "stop": "none",
  "tags": {
    "property1": "string",
    "property2": "string"
  },
  "udfs": [
    {
      "definition": "string",
      "language": "python"
    }
  ]
}
```

- `action_in_progress` (`put_pipeline.response.200.action_in_progress`; boolean, required)
- `action_text` (`put_pipeline.response.200.action_text`; string, required)
- `checkpoint_interval_micros` (`put_pipeline.response.200.checkpoint_interval_micros`; integer, required)
  - format: `int64` · minimum: `0`
- `created_at` (`put_pipeline.response.200.created_at`; integer, required)
  - format: `int64` · minimum: `0`
- `graph` (`put_pipeline.response.200.graph`; object, required)
  - `edges` (`put_pipeline.response.200.graph.edges`; array of object, required)
    - `dest_id` (`put_pipeline.response.200.graph.edges.dest_id`; integer, required)
      - format: `int32` · minimum: `0`
    - `edge_type` (`put_pipeline.response.200.graph.edges.edge_type`; string, required)
    - `key_type` (`put_pipeline.response.200.graph.edges.key_type`; string, required)
    - `src_id` (`put_pipeline.response.200.graph.edges.src_id`; integer, required)
      - format: `int32` · minimum: `0`
    - `value_type` (`put_pipeline.response.200.graph.edges.value_type`; string, required)
  - `nodes` (`put_pipeline.response.200.graph.nodes`; array of object, required)
    - `description` (`put_pipeline.response.200.graph.nodes.description`; string, required)
    - `node_id` (`put_pipeline.response.200.graph.nodes.node_id`; integer, required)
      - format: `int32` · minimum: `0`
    - `operator` (`put_pipeline.response.200.graph.nodes.operator`; string, required)
    - `parallelism` (`put_pipeline.response.200.graph.nodes.parallelism`; integer, required)
      - format: `int32` · minimum: `0`
- `id` (`put_pipeline.response.200.id`; string, required)
- `name` (`put_pipeline.response.200.name`; string, required)
- `preview` (`put_pipeline.response.200.preview`; boolean, required)
- `query` (`put_pipeline.response.200.query`; string, required)
- `stop` (`put_pipeline.response.200.stop`; string, required)
  - one of `"none"`, `"checkpoint"`, `"graceful"`, `"immediate"`, `"force"`
- `tags` (`put_pipeline.response.200.tags`; map of string, required) — User-defined key/value tags associated with the pipeline.
- `udfs` (`put_pipeline.response.200.udfs`; array of object, required)
  - `definition` (`put_pipeline.response.200.udfs.definition`; string, required)
  - `language` (`put_pipeline.response.200.udfs.language`; string, optional)
    - one of `"python"`, `"rust"`
- `action` (`put_pipeline.response.200.action`; string, optional, nullable)
  - one of `"none"`, `"checkpoint"`, `"graceful"`, `"immediate"`, `"force"`
- `state_url` (`put_pipeline.response.200.state_url`; string, optional, nullable) — Optional URL pointing to the state the pipeline was started from.

### 400

Bad request

#### Example

```json
{
  "error": "string"
}
```

- `error` (`put_pipeline.response.400.error`; string, required)


Source: https://www.arroyo.dev/docs/api/put-pipeline/index.md
