Quickstart

Upcoming release — Zylon 1.58These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the 1.57 documentation.

Start with ZylonGPT to send messages, or use the Workspace API to automate org and project setup.

Prerequisites

A token for your target API:
- Workspace-only token flow: Workspace Token Management
- One token across Workspace API + ZylonGPT API + Backoffice API: Backoffice Developer Console
Your Zylon hostname (replace {BASE_URL} in the examples).
For Workspace API: an account and an organization created in the workspace.

My first Zylon call

ZylonGPT API
Workspace API

Send your first message

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." }
    ]
  }'

Example response (your id and timestamps will differ):

{
  "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
  }
}

Stream responses (optional)

Set stream: true to receive 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." }
    ]
  }'

Example streamed events (truncated):

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"}

Workspace requests under /api/v1/app/* require the x-org header to target the correct organization. You can send either the organization slug (recommended) or the organization ID. In the examples below, use x-org: {org_slug}.

Authenticate

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}"
  }'

Example response:

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

Create a project

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"
  }'

Example response:

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

Upload an artifact

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'

Example response:

{
  "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
}

Create a thread and query the artifact

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
    }
  }'

Example response:

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

Next steps

ZylonGPT API overview

Learn the Messages, Artifacts, and Tools APIs.

Workspace API overview

Manage orgs, users, projects, and integrations.

Troubleshooting

401/403: your token is invalid, expired, lacks the required scope, or was issued for the wrong flow. Use Workspace Token Management for Workspace access, or Backoffice Developer Console for a token that works across Workspace, ZylonGPT, and Backoffice APIs.
404: Check your base URL. For ZylonGPT, use https://{BASE_URL}/api/gpt/v1/.
400 (model not found): Use "model": "default" unless you’ve been given a specific model name.
405: You’re using the wrong method. /messages is POST.

First Steps

Build with Zylon

Coding Agents

Prerequisites

My first Zylon call

Next steps

ZylonGPT API overview

Workspace API overview

Troubleshooting

​Prerequisites

​My first Zylon call

​Next steps

ZylonGPT API overview

Workspace API overview

​Troubleshooting

Prerequisites

My first Zylon call

Next steps

Troubleshooting