> ## 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.
# Quickstart
> Make your first Zylon API call in under 2 minutes.
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](/en/developer-manual/get-started/token-management)
* One token across Workspace API + ZylonGPT API + Backoffice API: [Backoffice Developer Console](/en/developer-manual/get-started/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
```bash theme={null}
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):
```json theme={null}
{
"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
}
}
```
Set `stream: true` to receive **Server-Sent Events (SSE)**.
```bash theme={null}
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):
```text theme={null}
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}`.
```bash theme={null}
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:
```json theme={null}
{
"id": "acct_6c8a1f3b2d4e5f7a",
"email": "sasha@auroralabs.com",
"provider": "Credentials",
"roles": ["AppAdmin"]
}
```
```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.",
"deadline": 1709337600,
"visibility": "Private"
}'
```
Example response:
```json theme={null}
{
"id": "proj_7a5c3e1b9d2f4a6c",
"name": "Customer Insights",
"visibility": "Private"
}
```
```bash theme={null}
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'
```
Example response:
```json theme={null}
{
"id": "artifact_2b4d6f8a1c3e5a7b",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"name": "Q1 Support Summary",
"type": "Document",
"state": "Ready",
"ingest_status": "Done",
"has_content": true
}
```
```bash theme={null}
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"
}'
```
```bash theme={null}
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:
```json theme={null}
{
"id": "inter_5a7b9c1d3e5f7a9b",
"state": "Completed"
}
```
## Next steps
Learn the Messages, Artifacts, and Tools APIs.
Manage orgs, users, projects, and integrations.
## Troubleshooting
* **401/403**: your token is invalid, expired, or issued for the wrong flow. Use [Workspace Token Management](/en/developer-manual/get-started/token-management) for Workspace-only access, or [Backoffice Developer Console](/en/developer-manual/get-started/developer-console) for a cross-API token.
* **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`.