> ## Documentation Index > Fetch the complete documentation index at: https://docs.infery.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a workflow > POST /v1/workflows Store a definition so you can run it by id, schedule it, or call it from another workflow as a `sub_pipeline` step. ## OpenAPI ````yaml openapi.json POST /v1/workflows openapi: 3.0.0 info: title: Infery Gateway description: >- Infery Inference Gateway — OpenAI-compatible API for LLMs, embeddings, images, audio, and video version: '1.0' contact: {} servers: - url: https://api.infery.ai description: Production - url: http://localhost:3001 description: Local security: [] tags: [] paths: /v1/workflows: post: tags: - Workflows summary: Create a reusable workflow description: >- Stores the definition as version 1 and returns its identity, not the whole row — read it back with `GET /v1/workflows/{id}`. Free: creating a workflow costs no credits and runs nothing. The definition is parsed by the write-boundary schema, which is STRICTER than what a stored row may contain: `pipeline_timeout_seconds` is refused outright (it was never enforced — bound a run with per-step `timeout_seconds` instead), and a `condition` on a step inside a container body is refused (`condition_in_container_body`). VISIBILITY: the new workflow is `private` to the creating user, so another member of the same workspace cannot see it until it is shared — except when the API key has no attributable creator (its creator was deleted or has left the workspace), in which case it is created `workspace`-scoped with `write`, because a private workflow with no owner would be unreachable by anyone. Every workflow the definition names through `sub_pipeline` must be one this caller could open, and the reference graph must be acyclic. operationId: PipelinesController_create[0] parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePipelineDto' responses: '201': description: Created. Version is always 1. content: application/json: schema: $ref: '#/components/schemas/PipelineWriteResultDto' '400': description: >- The definition failed the schema or the validator (unknown step type, unresolvable binding, `sub_pipeline` cycle, …). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '401': description: Unauthorized — invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '404': description: >- The definition references a `sub_pipeline` this caller cannot see (reported as not-found so the id cannot be probed). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' security: - ApiKey: [] components: schemas: CreatePipelineDto: type: object properties: name: type: string description: >- Human-readable name, unique to no one — two workflows in a workspace may share it. Identity is the returned `id`. maxLength: 120 example: Product shot → upscaled social set description: type: string description: >- Free text shown beside the workflow in the dashboard. Not interpreted, not passed to any step. maxLength: 2000 definition: type: object additionalProperties: true description: >- The workflow document: its `steps`, their bindings, and the `inputs` it declares. Validated by `parsePipelineDef` at this boundary, so a malformed definition is a 400 here and is never stored. The step union is defined in Zod (`schemas/pipeline-definition.schema.ts`) rather than as a class, which is why this is published as a free-form object rather than a modelled schema — read that file for the authoritative shape. required: - name - definition PipelineWriteResultDto: type: object properties: id: type: string description: Workflow UUID. Unchanged by an update. example: b0e9f2a4-2b1a-4c7d-9a3e-1f5c8d2e4b60 version: type: number description: >- The version this write left as latest. Always 1 from `POST`. From `PUT` it is the previous latest + 1 when the request carried a `definition`, and the UNCHANGED previous latest when it did not. example: 2 name: type: string description: The workflow name after the write. example: Weekly report required: - id - version - name ErrorResponseDto: type: object properties: error: description: >- The error envelope. Every non-2xx response from this API has this shape, so a client can parse failures without branching on the endpoint. allOf: - $ref: '#/components/schemas/ErrorDetailDto' required: - error ErrorDetailDto: type: object properties: message: type: string example: Model not found description: Human-readable error message type: type: string example: invalid_request_error description: Error category enum: - invalid_request_error - authentication_error - permission_error - quota_exceeded - rate_limit_error - server_error code: type: string example: model_not_found nullable: true description: >- Stable machine-readable error code. Branch on this rather than on `message`, which is prose and may be reworded. param: type: string example: model nullable: true description: >- Name of the request parameter that triggered the error. `null` when the error is not attributable to one field. job_id: type: string example: job_1hR9xTPZqK4mVLc2nJ7fY5wB description: >- Handle to work that is ALREADY RUNNING AND ALREADY BILLED, present on the few errors that carry one. When it is here, this is not a failure to retry — retrying pays twice. Collect the result from `GET /v1/images/jobs/{job_id}`, which serves every durable media job regardless of modality. Two situations produce it. A media generation that outruns the gateway's wait answers `504` with `code: "job_timeout"` and keeps working. And `POST /v1/audio/speech` answers **500** with `code: "artifact_unreadable"` when the speech was generated and settled but could not be read back from storage — the audio exists and is paid for; only this response failed. Declared here rather than per-endpoint because the rule is about the FIELD, not the status: if this is present, there is a paid-for result to collect. It was undeclared until now, so a client generated from this document could not see the one field that recovers money already spent. required: - message - type - code - param securitySchemes: ApiKey: type: apiKey in: header name: Authorization description: 'API key in format: Bearer inf_***' ````