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

# Pipelines y etapas

Requiere el permiso `pipelines:read`.


## OpenAPI

````yaml GET /pipelines
openapi: 3.1.0
info:
  title: Lumos API pública
  version: 1.0.0
  description: >
    API para integrar los sistemas de un cliente (ERP, sitio web, herramientas

    de automatización) con su CRM Lumos.


    ## Autenticación

    Cada integración tiene su key, que se crea en **Configuración →
    Integraciones**

    (solo administradores). La key identifica al tenant: no hace falta enviar

    `tenantId`. Se envía en cada request de servidor a servidor:

        x-api-key: lumos_live_...
        # o bien
        Authorization: Bearer lumos_live_...

    La key se muestra una sola vez. Para rotarla, crea una segunda key (máximo 2

    activas), cambia tu configuración y revoca la anterior.


    ## Permisos (scopes)

    Cada integración tiene scopes `{entidad}:read` / `{entidad}:write`. Un

    endpoint sin el scope necesario responde `403 insufficient_scope`.


    ## Reglas de negocio

    Los registros se crean y actualizan con las mismas reglas que la aplicación:

    campos obligatorios configurados por el tenant, condicionantes por etapa y

    validaciones. Los ids que envías (cuentas, contactos, usuarios, etapas)

    deben pertenecer a tu tenant.


    ## Campos personalizados

    Cuentas, contactos y oportunidades aceptan y devuelven

    `customFields: { <key>: valor }`. Las claves y tipos de tu tenant salen de

    `GET /custom-fields?entity=account|contact|opportunity`. Formato por tipo:


    | Tipo | Valor |

    |---|---|

    | `text` | `"texto"` (respeta `maxLength`) |

    | `number` | `12.5` |

    | `currency` | `1500` o `{ "amount": 1500, "currency": "USD" }` |

    | `date` | `"2026-11-30"` |

    | `list` | `"Pyme"` (una de `options`, sin distinguir mayúsculas) |

    | `multi_list` | `["CRM", "IA"]` |


    `null` borra el valor. Los campos con `required: true` son obligatorios al

    crear. Una clave desconocida o un valor inválido responde `422`.


    ## Paginación

    Los listados devuelven `{ data, nextCursor }`, ordenados por `updatedAt`

    ascendente. Pide la página siguiente con `?cursor=<nextCursor>` hasta que

    `nextCursor` sea `null`. Para sincronizar cambios usa `updatedSince`.


    ## Idempotencia

    En los `POST`, envía `Idempotency-Key: <uuid>`. Si reintentas con la misma

    key y el mismo body en las siguientes 24 h, recibes la respuesta original

    (con `Idempotent-Replayed: true`) sin crear un duplicado.


    ## Límites

    300 requests por minuto por key. Cabeceras `X-RateLimit-Limit`,

    `X-RateLimit-Remaining` y `X-RateLimit-Reset`; al excederlo, `429` con

    `Retry-After`.


    ## Errores

    Siempre con la forma `{ "error": { "code", "message", "details"? } }`.


    | HTTP | code | Cuándo |

    |---|---|---|

    | 400 | `validation_error`, `invalid_cursor`, `bad_request` | Request mal
    formado |

    | 401 | `unauthorized` | Key ausente, inválida o revocada |

    | 403 | `insufficient_scope` | La integración no tiene el scope |

    | 404 | `not_found` | El recurso no existe en tu tenant |

    | 409 | `duplicate` | Ya existe (cuenta por nombre, contacto por email);
    `details.existingId` |

    | 409 | `conflict`, `tenant_without_admin` | Conflicto de estado |

    | 422 | `validation_error`, `invalid_reference`, `idempotency_key_reused` |
    Reglas de negocio |

    | 422 | `unknown_custom_field`, `invalid_custom_field` | Campo personalizado
    inexistente o valor inválido |

    | 429 | `rate_limited` | Límite excedido |

    | 500 | `internal_error` | Error nuestro; reintenta con la misma
    Idempotency-Key |
servers:
  - url: https://{host}/integrations/v1
    variables:
      host:
        default: platform.lumosai.biz
security:
  - apiKey: []
  - bearer: []
paths:
  /pipelines:
    get:
      tags:
        - Referencia
      summary: Pipelines y etapas
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Pipeline'
        default:
          $ref: '#/components/responses/Error'
components:
  schemas:
    Pipeline:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        isDefault:
          type: boolean
        isActive:
          type: boolean
        stages:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              key:
                type:
                  - string
                  - 'null'
              name:
                type: string
              category:
                type:
                  - string
                  - 'null'
              order:
                type:
                  - number
                  - 'null'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
    bearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.