Proyectos

Próxima versión — Zylon 1.58Esta documentación se publica antes del lanzamiento para que puedas preparar tus integraciones de API. La imagen de la versión todavía no está disponible. Para instalaciones con 1.57, consulta la documentación de 1.57.

Los proyectos son la unidad del espacio de trabajo que contiene hilos, artefactos y contexto de equipo. Usa estos endpoints para crear y configurar proyectos, transferir la propiedad e iniciar chats con alcance de proyecto.

Solicitud básica y respuesta

Crea un proyecto con POST /api/v1/app/project.

Parametros del endpoint

Tipo	Nombre	Requerido	Notas
Body	`name`	Si	Nombre del proyecto.
Body	`goal`	No	Objetivo o descripcion del proyecto.
Body	`visibility`	No	`Public` o `Private`; por defecto `Private`.

curl -X POST "https://{BASE_URL}/api/v1/app/project" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Insights",
    "goal": "Summarize weekly support trends.",
    "visibility": "Private"
  }'

Ejemplo de respuesta

{
  "id": "{projectID}",
  "name": "Customer Insights",
  "goal": "Summarize weekly support trends.",
  "default_member_role": "Viewer",
  "default_role_enabled": false,
  "visibility": "Private",
  "use_citations": true,
  "use_system_prompt": true,
  "is_pinned": false
}

Campos de respuesta del proyecto

Crear, obtener, PUT, PATCH y DELETE devuelven este modelo JSON con 200. Los campos nulos pueden omitirse. Al crear se usa Viewer, default_role_enabled:false, use_citations:true, use_system_prompt:true. Los miembros anidados usan el modelo de Miembros del proyecto.

Campo	Tipo	Significado
`id`	string	ID de proyecto.
`name`	string	Nombre.
`goal`	string or null	Objetivo opcional.
`default_member_role`	string	`Viewer`, `Commenter`, `Editor`, `Admin`, `Owner`.
`default_role_enabled`	boolean	Si los no miembros reciben el rol predeterminado.
`visibility`	string	`Public` o `Private`.
`member_count`	integer or null	Total incluido en operaciones de detalle/lista cuando existe.
`members`	object[] or null	Miembros cuando se solicitan; cada uno tiene `id` (ID de miembro), `role`, `account`, `is_project_member`. Consulta Miembros del proyecto para el modelo de cuenta.
`project_context`	string or null	Instrucciones opcionales del proyecto.
`use_citations`	boolean	Ajuste de citas.
`use_system_prompt`	boolean	Ajuste del system prompt.
`is_pinned`	boolean or null	Estado de fijacion del miembro actual cuando existe; las respuestas de modificacion usan false por defecto.

Obtener un proyecto

curl "https://{BASE_URL}/api/v1/app/project/{projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Ejemplo de respuesta

{
  "id": "{projectID}",
  "name": "Customer Insights",
  "goal": "Summarize weekly support trends.",
  "default_member_role": "Viewer",
  "default_role_enabled": false,
  "visibility": "Private",
  "use_citations": true,
  "use_system_prompt": true,
  "is_pinned": false,
  "member_count": 1
}

Actualizar un proyecto

PUT y PATCH aceptan los mismos campos opcionales. Los valores omitidos o null mantienen los ajustes actuales. Se recortan los espacios de project_context; una cadena vacia o de espacios lo elimina. La instalacion limita su longitud. default_role_enabled:true hace el proyecto Public; false lo hace Private, con prioridad sobre visibility si tambien se envia.

PUT
PATCH

Parametros del endpoint

Tipo	Nombre	Requerido	Notas
Path	`projectID`	Si	Identificador del proyecto.
Body	`name`	No	Nombre del proyecto.
Body	`goal`	No	Objetivo o descripcion del proyecto.
Body	`visibility`	No	`Public` o `Private`.
Body	`project_context`	No	Contexto del proyecto.
Body	`default_member_role`	No	`Viewer`, `Commenter`, `Editor`, `Admin` u `Owner`.
Body	`default_role_enabled`	No	Habilita el rol predeterminado.
Body	`use_citations`	No	Habilita las citas del chat del proyecto.
Body	`use_system_prompt`	No	Habilita el system prompt del chat del proyecto.

curl -X PUT "https://{BASE_URL}/api/v1/app/project/{projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Insights",
    "goal": "Summarize weekly support and churn signals.",
    "visibility": "Public",
    "project_context": "Support analytics for Q1.",
    "default_member_role": "Editor",
    "default_role_enabled": true,
    "use_citations": true,
    "use_system_prompt": true
  }'

Ejemplo de respuesta

{
  "id": "{projectID}",
  "name": "Customer Insights",
  "goal": "Summarize weekly support and churn signals.",
  "default_member_role": "Editor",
  "default_role_enabled": true,
  "visibility": "Public",
  "use_citations": true,
  "use_system_prompt": true,
  "is_pinned": false,
  "project_context": "Support analytics for Q1."
}

Parametros del endpoint

Tipo	Nombre	Requerido	Notas
Path	`projectID`	Si	Identificador del proyecto.
Body	Los campos de PUT anteriores	No	Actualizacion parcial; envia solo los campos a cambiar.

curl -X PATCH "https://{BASE_URL}/api/v1/app/project/{projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_context": "Support analytics for Q1 with strict PII handling."
  }'

Ejemplo de respuesta

{
  "id": "{projectID}",
  "name": "Customer Insights",
  "goal": "Summarize weekly support trends.",
  "default_member_role": "Viewer",
  "default_role_enabled": false,
  "visibility": "Private",
  "use_citations": true,
  "use_system_prompt": true,
  "is_pinned": false,
  "project_context": "Support analytics for Q1 with strict PII handling."
}

Eliminar un proyecto

curl -X DELETE "https://{BASE_URL}/api/v1/app/project/{projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Ejemplo de respuesta

{
  "id": "{projectID}",
  "name": "Customer Insights",
  "goal": "Summarize weekly support trends.",
  "default_member_role": "Viewer",
  "default_role_enabled": false,
  "visibility": "Private",
  "use_citations": true,
  "use_system_prompt": true,
  "is_pinned": false
}

DELETE elimina el proyecto y devuelve su modelo, en lugar de 204 No Content.

Salir de un proyecto

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/leave" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Ejemplo de respuesta

HTTP/1.1 200 OK

200

Transferir la propiedad de un proyecto

Parametros del endpoint

Tipo	Nombre	Requerido	Notas
Path	`projectID`	Si	Identificador del proyecto.
Body	`old_owner_ws_member_id`	Si	ID de miembro del espacio de trabajo del propietario actual.
Body	`new_owner_ws_member_id`	Si	ID de miembro del espacio de trabajo del nuevo propietario; debe identificar a un miembro del proyecto.

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/transfer" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "old_owner_ws_member_id": "{currentOwnerWsMemberId}",
    "new_owner_ws_member_id": "{newOwnerWsMemberId}"
  }'

Ejemplo de respuesta

{
  "id": "{newOwnerWsMemberId}",
  "role": "Owner",
  "account": {
    "id": "{accountId}",
    "state": "Active",
    "email": "jordan@example.com",
    "name": "Jordan Lee",
    "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
    "provider": "Credentials",
    "roles": ["Workspace"],
    "created_at": "2026-01-10T09:00:00Z",
    "updated_at": "2026-02-07T09:20:12Z"
  },
  "is_project_member": true
}

Información del miembro del espacio de trabajo en el proyecto

Obtén la información del proyecto para un miembro específico del espacio de trabajo o actualízala para el miembro autenticado actualmente.

Obtener información del miembro
Actualizar información del miembro actual

Parametros del endpoint

Tipo	Nombre	Obligatorio	Notas
Path	`projectID`	Si	Identificador del proyecto.
Path	`wsMemberId`	Si	ID del miembro del espacio de trabajo. No se admite el valor `me`.

curl "https://{BASE_URL}/api/v1/app/project/{projectID}/info/{wsMemberId}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Ejemplo de respuesta

{
  "id": "{wsMemberId}",
  "project_id": "{projectId}",
  "is_pinned": true
}

Parametros del endpoint

Tipo	Nombre	Requerido	Notas
Path	`projectID`	Si	Identificador del proyecto.
Body	`is_pinned`	Si	Fija o desfija el proyecto para el miembro del espacio de trabajo autenticado actualmente.

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/info" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "is_pinned": true
  }'

Ejemplo de respuesta

{
  "id": "{wsMemberId}",
  "project_id": "{projectId}",
  "is_pinned": true
}

Chat con alcance de proyecto

Usa el endpoint actual POST /api/v1/app/chat con project_id en el cuerpo. La URL de compatibilidad POST /api/v1/app/project/{projectID}/chat sigue disponible; migra los clientes al endpoint actual. La ruta actual siempre devuelve SSE.

Parametros del endpoint

Tipo	Nombre	Obligatorio	Notas
Body	`project_id`	Si	Proyecto cuyo contexto se usa.
Body	`pgpt`	Si	Solicitud de Messages con exactamente un mensaje de usuario.
Body	`artifacts`	No	Selectores de artefactos por alcance.

curl -N -X POST "https://{BASE_URL}/api/v1/app/chat" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "artifacts": {
      "document": [
        {
          "scope": "project",
          "all_artifacts": true
        }
      ]
    },
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "Summarize the latest support trends in three bullets."
            }
          ]
        }
      ],
      "max_tokens": 80,
      "temperature": 0.2
    }
  }'

Consulta Chats para los eventos SSE y los modelos de cuerpo y seleccion de artefactos. La URL antigua del proyecto respeta pgpt.stream: true transmite eventos; false devuelve una respuesta de Message.

Errores y casos límite

403: no eres miembro del proyecto.
404: proyecto no encontrado.
409: el miembro del espacio de trabajo de destino no es elegible para transferir.

Primeros pasos

Construye con Zylon

Coding Agents

Solicitud básica y respuesta

Campos de respuesta del proyecto

Obtener un proyecto

Actualizar un proyecto

Eliminar un proyecto

Salir de un proyecto

Transferir la propiedad de un proyecto

Información del miembro del espacio de trabajo en el proyecto

Chat con alcance de proyecto

Errores y casos límite

​Solicitud básica y respuesta

​Campos de respuesta del proyecto

​Obtener un proyecto

​Actualizar un proyecto

​Eliminar un proyecto

​Salir de un proyecto

​Transferir la propiedad de un proyecto

​Información del miembro del espacio de trabajo en el proyecto

​Chat con alcance de proyecto

​Errores y casos límite

Solicitud básica y respuesta

Campos de respuesta del proyecto

Obtener un proyecto

Actualizar un proyecto

Eliminar un proyecto

Salir de un proyecto

Transferir la propiedad de un proyecto

Información del miembro del espacio de trabajo en el proyecto

Chat con alcance de proyecto

Errores y casos límite