Quickstart

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

Prerequisites

An API token. See Token Management.
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@auroralabs.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

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "InlineText",
    "source": "User",
    "name": "Q1 Support Summary",
    "props": {
      "content": "Ticket volume rose 12% week-over-week. Billing issues drove 38% of cases."
    }
  }'

Example response:

{
  "id": "artifact_2b4d6f8a1c3e5a7b",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support Summary",
  "type": "InlineText",
  "ingest_status": "NotApplicable"
}

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 or expired. See Token Management.
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

Prerequisites

My first Zylon call

Next steps

ZylonGPT API overview

Workspace API overview

Troubleshooting

First Steps

Build with Zylon

​Prerequisites

​My first Zylon call

​Next steps

ZylonGPT API overview

Workspace API overview

​Troubleshooting

Prerequisites

My first Zylon call

Next steps

Troubleshooting