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

# Proyectos

> Crea proyectos, actualiza metadatos y ejecuta chats a nivel de proyecto.

<Warning>
  **Próxima versión — Zylon 1.58**

  Esta 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](/es/v1.57/overview).
</Warning>

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`.

<Accordion title="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`. |
</Accordion>

```bash theme={null}
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"
  }'
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "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
  }
  ```
</Accordion>

### 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](/es/v1.58/developer-manual/build-with-zylon/workspace-api/projects/project-member).

| 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

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

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "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
  }
  ```
</Accordion>

## 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.

<Tabs>
  <Tab title="PUT">
    <Accordion title="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. |
    </Accordion>

    ```bash theme={null}
    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
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "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."
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="PATCH">
    <Accordion title="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. |
    </Accordion>

    ```bash theme={null}
    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."
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "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."
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

## Eliminar un proyecto

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

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "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
  }
  ```
</Accordion>

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

## Salir de un proyecto

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

<Accordion title="Ejemplo de respuesta">
  ```text theme={null}
  HTTP/1.1 200 OK

  200
  ```
</Accordion>

## Transferir la propiedad de un proyecto

<Accordion title="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. |
</Accordion>

```bash theme={null}
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}"
  }'
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "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
  }
  ```
</Accordion>

## 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.

<Tabs>
  <Tab title="Obtener información del miembro">
    <Accordion title="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`. |
    </Accordion>

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

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "{wsMemberId}",
        "project_id": "{projectId}",
        "is_pinned": true
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Actualizar información del miembro actual">
    <Accordion title="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. |
    </Accordion>

    ```bash theme={null}
    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
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "{wsMemberId}",
        "project_id": "{projectId}",
        "is_pinned": true
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

## 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.

<Accordion title="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. |
</Accordion>

```bash theme={null}
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](/es/v1.58/developer-manual/build-with-zylon/workspace-api/chats/threads#chat-puntual) 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.


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