Guía rápida

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.

Empieza con ZylonGPT para enviar mensajes o usa la Workspace API para automatizar organizaciones y proyectos.

Requisitos previos

Un token para la API que vas a usar:
- Flujo de token solo para Workspace: Gestión de tokens de Workspace
- Un token para Workspace API + ZylonGPT API + Backoffice API: Backoffice Developer Console
El nombre de host de Zylon (sustituye {BASE_URL} en los ejemplos).
Para la Workspace API: una cuenta y una organización creadas en el Workspace.

Mi primera llamada a Zylon

ZylonGPT API
Workspace API

Envía tu primer mensaje

curl -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "max_tokens": 64,
    "messages": [
      { "role": "user", "content": "Write a one-sentence product description for Zylon." }
    ]
  }'

Ejemplo de respuesta (tu id y timestamps variarán):

{
  "id": "msg_d88cec8ffdf344dcafddb72026ead6be",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "start_timestamp": "2026-02-06T13:16:10.412540Z",
      "stop_timestamp": "2026-02-06T13:16:10.543884Z",
      "text": "Zylon is a private AI platform for building secure, tool-using assistants and workflows."
    }
  ],
  "model": "private-gpt",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 93,
    "output_tokens": 18
  }
}

Streaming (opcional)

Establece stream: true para recibir Server-Sent Events (SSE).

curl -N -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "default",
    "stream": true,
    "max_tokens": 32,
    "messages": [
      { "role": "user", "content": "Give a three-word tagline for a productivity app." }
    ]
  }'

Ejemplo de eventos (recortado):

event: message_start
data: {"type":"message_start","message":{"id":"msg_b55d29718361410bad4f80f8f67c6b72","type":"message","role":"assistant","content":[],"model":"private-gpt","usage":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"block_id":"block_019c331ac11375cea03f7e0fb7a2a044","delta":{"type":"text_delta","text":"Focus"}}

event: message_stop
data: {"type":"message_stop"}

Las solicitudes de Workspace bajo /api/v1/app/* requieren la cabecera x-org para apuntar a la organización correcta. Puedes enviar el slug de la organización (recomendado) o el ID de la organización. En los ejemplos siguientes, usa x-org: {org_slug}.

Inicia sesión

curl -X POST "https://{BASE_URL}/api/v1/auth/login" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "{username}",
    "password": "{password}"
  }'

Ejemplo de respuesta:

{
  "id": "acct_6c8a1f3b2d4e5f7a",
  "email": "sasha@example.com",
  "provider": "Credentials",
  "roles": ["AppAdmin"]
}

Crea un proyecto

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.",
    "deadline": 1709337600,
    "visibility": "Private"
  }'

Ejemplo de respuesta:

{
  "id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Customer Insights",
  "visibility": "Private"
}

Sube un artefacto

printf 'Q1 support summary.\n' > q1-support-summary.txt

curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -F 'project_id={projectID}' \
  -F 'type=Document' \
  -F 'name=Q1 Support Summary' \
  -F 'props={
    "content_type":"text/plain",
    "file_name":"q1-support-summary.txt",
    "content_length":20
  };type=application/json' \
  -F 'file_data=@./q1-support-summary.txt;type=text/plain'

Ejemplo de respuesta:

{
  "id": "artifact_2b4d6f8a1c3e5a7b",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support Summary",
  "type": "Document",
  "source": "User",
  "state": "Published",
  "ingest_status": "NotStarted",
  "keep_file_after_ingestion": true
}

Crea un hilo y consulta el artefacto

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/thread" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Support Brief",
    "visibility": "Private"
  }'

curl -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "{threadID}",
    "artifact_ids": ["{artifactID}"],
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            { "type": "text", "text": "Summarize the artifact in three bullets." }
          ]
        }
      ],
      "max_tokens": 96,
      "temperature": 0.2
    }
  }'

Ejemplo de respuesta:

{
  "id": "inter_5a7b9c1d3e5f7a9b",
  "state": "Completed"
}

Próximos pasos

Visión general de ZylonGPT API

Aprende sobre Mensajes, Artefactos y Herramientas.

Visión general de Workspace API

Gestiona organizaciones, usuarios, proyectos e integraciones.

Solución de problemas

401/403: token inválido, caducado, sin el scope necesario o emitido para el flujo incorrecto. Usa Gestión de tokens de Workspace para acceder a Workspace, o Backoffice Developer Console para un token que funcione en las APIs de Workspace, ZylonGPT y Backoffice.
404: revisa tu base URL. Para ZylonGPT usa https://{BASE_URL}/api/gpt/v1/.
400 (model not found): usa "model": "default".
405: método incorrecto. /messages es POST.

Primeros pasos

Construye con Zylon

Coding Agents

Guía rápida

Requisitos previos

Mi primera llamada a Zylon

Próximos pasos

Visión general de ZylonGPT API

Visión general de Workspace API

Solución de problemas

​Requisitos previos

​Mi primera llamada a Zylon

​Próximos pasos

Visión general de ZylonGPT API

Visión general de Workspace API

​Solución de problemas

Requisitos previos

Mi primera llamada a Zylon

Próximos pasos

Solución de problemas