> ## Documentation Index > Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Criar ou clonar Flow > Cria um Flow em `DRAFT`, ou clona um existente. Responde `201` com `{id, metaFlowId}` — só esses dois campos, não o Flow inteiro. Aceita exatamente `name`, `categories` e `cloneFromFlowId`: qualquer outra chave é RECUSADA com 400 `FLOW_UNKNOWN_FIELDS`, nunca ignorada, para que `{"status":"PUBLISHED"}` não responda 201 e deixe você concluir que publicou. O número e a WABA vêm da chave — mandar `whatsappNumberId`, `wabaId` ou `metaWabaId` dá 400 `FLOW_NUMBER_FROM_KEY`. Permissão `flows:manage` (ADMIN e acima). **Exige chave com escopo de número.** Uma chave de tenant precisa nomear o número no header `x-whatsapp-number-id`, senão recebe 403 `TENANT_SCOPE_NOT_ALLOWED`. ## OpenAPI ````yaml openapi.pt.json POST /v1/flows openapi: 3.1.0 info: title: API Pilot Status version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- API REST pública do Pilot Status. Autentique com o header `x-api-key: ps_...` (ou `x-api-key-id`). Base URL: https://pilotstatus.com.br servers: - url: https://pilotstatus.com.br security: - apiKey: [] - apiKeyId: [] paths: /v1/flows: post: tags: - Flows summary: Criar ou clonar Flow description: >- Cria um Flow em `DRAFT`, ou clona um existente. Responde `201` com `{id, metaFlowId}` — só esses dois campos, não o Flow inteiro. Aceita exatamente `name`, `categories` e `cloneFromFlowId`: qualquer outra chave é RECUSADA com 400 `FLOW_UNKNOWN_FIELDS`, nunca ignorada, para que `{"status":"PUBLISHED"}` não responda 201 e deixe você concluir que publicou. O número e a WABA vêm da chave — mandar `whatsappNumberId`, `wabaId` ou `metaWabaId` dá 400 `FLOW_NUMBER_FROM_KEY`. Permissão `flows:manage` (ADMIN e acima). **Exige chave com escopo de número.** Uma chave de tenant precisa nomear o número no header `x-whatsapp-number-id`, senão recebe 403 `TENANT_SCOPE_NOT_ALLOWED`. operationId: post_flows requestBody: required: true content: application/json: schema: type: object required: - name - categories properties: name: type: string minLength: 1 description: Nome do Flow. Não vazio; espaços das pontas são removidos. example: Agendamento v2 categories: type: array minItems: 1 items: type: string enum: - SIGN_UP - SIGN_IN - APPOINTMENT_BOOKING - LEAD_GENERATION - CONTACT_US - CUSTOMER_SUPPORT - SURVEY - OTHER description: >- Uma ou mais do conjunto fechado da Meta. Valor fora dele dá 400 `FLOW_CATEGORY_INVALID`. example: - APPOINTMENT_BOOKING cloneFromFlowId: type: string description: >- O id **LOCAL** do Flow de origem — o campo `id` que `GET /v1/flows` devolve, **nunca** o `metaFlowId`. Confundir os dois é o engano natural e não conseguimos detectá-lo por você: ambos são strings opacas, e a Meta responde com o erro dela. O `metaFlowId` também é anulável (um rascunho nunca enviado), então um id da Meta não teria o que resolver. Omita para criar do zero; `null` é recusado. example: cmf1a2b3c4d5e6f7g8h9i0j1 example: name: Agendamento v2 categories: - APPOINTMENT_BOOKING cloneFromFlowId: cmf1a2b3c4d5e6f7g8h9i0j1 responses: '201': description: Flow criado em DRAFT content: application/json: example: id: cmf1a2b3c4d5e6f7g8h9i0j1 metaFlowId: '1122334455' '400': description: >- `FLOW_BODY_INVALID` (o payload não fez parse), `FLOW_NAME_REQUIRED`, `FLOW_CATEGORY_INVALID`, `FLOW_CLONE_SOURCE_INVALID`, `FLOW_UNKNOWN_FIELDS`, `FLOW_NUMBER_FROM_KEY`, ou uma recusa da Meta (Graph) content: application/json: schema: type: object properties: error: type: string description: Portuguese half errorEN: type: string description: English half code: type: string example: error: >- categories é obrigatório: uma lista não vazia de SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY, OTHER. errorEN: >- categories is required: a non-empty array of SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY, OTHER. code: FLOW_CATEGORY_INVALID '401': description: Header `x-api-key` / `x-api-key-id` ausente ou inválido content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unauthorized '403': description: >- Chave com escopo de tenant usada em endpoint com escopo de número, ou o papel da chave não tem a permissão content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Tenant-scoped keys cannot call number endpoints code: TENANT_SCOPE_NOT_ALLOWED '404': description: >- `cloneFromFlowId` não nomeia nenhum Flow seu. Neste verbo é o único id que você fornece content: application/json: schema: type: object properties: error: type: string description: Portuguese half errorEN: type: string description: English half code: type: string example: error: Flow não encontrado para o número desta chave. errorEN: Flow not found for this key's number. code: FLOW_NOT_FOUND '409': description: >- O Flow saiu de `DRAFT`. Publicar é irreversível na Meta — clone para começar uma versão nova content: application/json: schema: type: object properties: error: type: string description: Portuguese half errorEN: type: string description: English half code: type: string example: error: >- Este Flow já foi publicado na Meta e não pode mais ser alterado. Clone-o para criar uma nova versão. errorEN: >- This Flow is already published on Meta and can no longer be changed. Clone it to create a new version. code: FLOW_NOT_DRAFT '422': description: >- O número da chave não é Meta (API Oficial), ou não tem WABA associada content: application/json: schema: type: object properties: error: type: string description: Portuguese half errorEN: type: string description: English half code: type: string example: error: >- Flows existem apenas em números Meta (API Oficial). O número desta chave não é Meta ou não tem uma WABA associada — use uma chave de um número Meta. errorEN: >- Flows only exist on Meta (Cloud API) numbers. This key's number is not a Meta number, or has no WABA behind it — use a key bound to a Meta number. code: FLOW_REQUIRES_META_NUMBER '429': description: Limite de taxa excedido content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Too many requests '500': description: Erro interno. Nunca carrega a mensagem interna — essa fica no log content: application/json: schema: type: object properties: error: type: string description: Portuguese half errorEN: type: string description: English half code: type: string example: error: Erro interno do servidor. errorEN: Internal server error. code: INTERNAL_ERROR components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Sua chave de API ps_ apiKeyId: type: apiKey in: header name: x-api-key-id description: Id da chave de API (alternativa ao x-api-key) ````