Guía rápida

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@auroralabs.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

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

Ejemplo de respuesta:

{
  "id": "artifact_2b4d6f8a1c3e5a7b",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support Summary",
  "type": "Document",
  "state": "Ready",
  "ingest_status": "Done",
  "has_content": 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 o emitido para el flujo incorrecto. Usa Gestión de tokens de Workspace para acceso solo a Workspace, o Backoffice Developer Console para un token multi-API.
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.

​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