> ## 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. # Crear tarea Requiere el permiso `tasks:write`. ## OpenAPI ````yaml POST /tasks 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: { : 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=` hasta que `nextCursor` sea `null`. Para sincronizar cambios usa `updatedSince`. ## Idempotencia En los `POST`, envía `Idempotency-Key: `. 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: /tasks: post: tags: - Tareas summary: Crear tarea parameters: - $ref: '#/components/parameters/idempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskInput' responses: '201': $ref: '#/components/responses/Task' default: $ref: '#/components/responses/Error' components: parameters: idempotencyKey: name: Idempotency-Key in: header schema: type: string maxLength: 200 schemas: TaskInput: allOf: - $ref: '#/components/schemas/TaskPatch' - required: - title description: 'priority por defecto: medium.' TaskPatch: type: object properties: title: type: string description: type: string priority: $ref: '#/components/schemas/TaskPriority' status: $ref: '#/components/schemas/TaskStatus' dueDate: type: string format: date-time relatedTo: $ref: '#/components/schemas/RelatedTo' assignedTo: type: string format: uuid Task: type: object properties: id: type: string format: uuid title: type: string description: type: - string - 'null' priority: $ref: '#/components/schemas/TaskPriority' status: $ref: '#/components/schemas/TaskStatus' dueDate: type: - string - 'null' format: date-time relatedTo: oneOf: - $ref: '#/components/schemas/RelatedTo' - type: 'null' assignedTo: type: - string - 'null' format: uuid closedAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true TaskPriority: type: string enum: - low - medium - high TaskStatus: type: string enum: - pending - completed - canceled RelatedTo: type: object required: - type - id properties: type: $ref: '#/components/schemas/RelatedType' id: type: string format: uuid RelatedType: type: string enum: - account - contact - opportunity responses: Task: description: OK content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Task' 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.