Projects

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.

Projects are the workspace unit that holds threads, artifacts, and team context. Use these endpoints to create and configure projects, transfer ownership, and start project-scoped chats.

Basic request and response

Create a project with POST /api/v1/app/project.

Endpoint parameters

Type	Name	Required	Notes
Body	`name`	Yes	Project name.
Body	`goal`	No	Project goal or description.
Body	`visibility`	No	`Public` or `Private`; defaults to `Private`.

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

Example response

{
  "id": "{projectID}",
  "name": "Customer Insights",
  "goal": "Summarize weekly support trends.",
  "default_member_role": "Viewer",
  "default_role_enabled": false,
  "visibility": "Private",
  "use_citations": true,
  "use_system_prompt": true,
  "is_pinned": false
}

Project response fields

Create, get, PUT, PATCH and DELETE return this JSON model with 200. Null fields may be omitted. Creation defaults to Viewer, default_role_enabled:false, use_citations:true, use_system_prompt:true. Nested members use the Project Members model.

Field	Type	Meaning
`id`	string	Project ID.
`name`	string	Project name.
`goal`	string or null	Optional goal.
`default_member_role`	string	`Viewer`, `Commenter`, `Editor`, `Admin`, `Owner`.
`default_role_enabled`	boolean	Whether nonmembers receive the default role.
`visibility`	string	`Public` or `Private`.
`member_count`	integer or null	Count supplied by detail/list operations when available.
`members`	object[] or null	Members when requested; each has `id` (workspace-member ID), `role`, `account`, `is_project_member`. See Project Members for the account model.
`project_context`	string or null	Optional project instructions.
`use_citations`	boolean	Citation setting.
`use_system_prompt`	boolean	System prompt setting.
`is_pinned`	boolean or null	Current member pinning state when populated; mutation responses default to false.

Get a project

curl "https://{BASE_URL}/api/v1/app/project/{projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Example response

{
  "id": "{projectID}",
  "name": "Customer Insights",
  "goal": "Summarize weekly support trends.",
  "default_member_role": "Viewer",
  "default_role_enabled": false,
  "visibility": "Private",
  "use_citations": true,
  "use_system_prompt": true,
  "is_pinned": false,
  "member_count": 1
}

Update a project

PUT and PATCH accept the same optional fields. Omitted or null values preserve existing settings. project_context is trimmed; an empty or whitespace-only string clears it. The deployment limits its length. Setting default_role_enabled:true makes the project Public; false makes it Private, overriding a simultaneous visibility field.

PUT
PATCH

Endpoint parameters

Type	Name	Required	Notes
Path	`projectID`	Yes	Project identifier.
Body	`name`	No	Project name.
Body	`goal`	No	Project goal or description.
Body	`visibility`	No	`Public` or `Private`.
Body	`project_context`	No	Project-level context.
Body	`default_member_role`	No	`Viewer`, `Commenter`, `Editor`, `Admin`, or `Owner`.
Body	`default_role_enabled`	No	Enables the default member role.
Body	`use_citations`	No	Enable citation features for project chat.
Body	`use_system_prompt`	No	Enable the system prompt for project chat.

curl -X PUT "https://{BASE_URL}/api/v1/app/project/{projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Insights",
    "goal": "Summarize weekly support and churn signals.",
    "visibility": "Public",
    "project_context": "Support analytics for Q1.",
    "default_member_role": "Editor",
    "default_role_enabled": true,
    "use_citations": true,
    "use_system_prompt": true
  }'

Example response

{
  "id": "{projectID}",
  "name": "Customer Insights",
  "goal": "Summarize weekly support and churn signals.",
  "default_member_role": "Editor",
  "default_role_enabled": true,
  "visibility": "Public",
  "use_citations": true,
  "use_system_prompt": true,
  "is_pinned": false,
  "project_context": "Support analytics for Q1."
}

Endpoint parameters

Type	Name	Required	Notes
Path	`projectID`	Yes	Project identifier.
Body	The PUT fields above	No	Partial update; send only fields to change.

curl -X PATCH "https://{BASE_URL}/api/v1/app/project/{projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_context": "Support analytics for Q1 with strict PII handling."
  }'

Example response

{
  "id": "{projectID}",
  "name": "Customer Insights",
  "goal": "Summarize weekly support trends.",
  "default_member_role": "Viewer",
  "default_role_enabled": false,
  "visibility": "Private",
  "use_citations": true,
  "use_system_prompt": true,
  "is_pinned": false,
  "project_context": "Support analytics for Q1 with strict PII handling."
}

Delete a project

curl -X DELETE "https://{BASE_URL}/api/v1/app/project/{projectID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Example response

{
  "id": "{projectID}",
  "name": "Customer Insights",
  "goal": "Summarize weekly support trends.",
  "default_member_role": "Viewer",
  "default_role_enabled": false,
  "visibility": "Private",
  "use_citations": true,
  "use_system_prompt": true,
  "is_pinned": false
}

DELETE removes the project and returns its project model, rather than 204 No Content.

Leave a project

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/leave" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Example response

HTTP/1.1 200 OK

200

Transfer project ownership

Endpoint parameters

Type	Name	Required	Notes
Path	`projectID`	Yes	Project identifier.
Body	`old_owner_ws_member_id`	Yes	Current owner’s workspace member ID.
Body	`new_owner_ws_member_id`	Yes	New owner’s workspace member ID; must identify a project member.

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/transfer" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "old_owner_ws_member_id": "{currentOwnerWsMemberId}",
    "new_owner_ws_member_id": "{newOwnerWsMemberId}"
  }'

Example response

{
  "id": "{newOwnerWsMemberId}",
  "role": "Owner",
  "account": {
    "id": "{accountId}",
    "state": "Active",
    "email": "jordan@example.com",
    "name": "Jordan Lee",
    "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
    "provider": "Credentials",
    "roles": ["Workspace"],
    "created_at": "2026-01-10T09:00:00Z",
    "updated_at": "2026-02-07T09:20:12Z"
  },
  "is_project_member": true
}

Project workspace member info

Get project information for a specified workspace member, or update it for the currently authenticated workspace member.

Get member info
Update current member info

Endpoint parameters

Type	Name	Required	Notes
Path	`projectID`	Yes	Project identifier.
Path	`wsMemberId`	Yes	Workspace-member ID. The value `me` is not supported.

curl "https://{BASE_URL}/api/v1/app/project/{projectID}/info/{wsMemberId}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Example response

{
  "id": "{wsMemberId}",
  "project_id": "{projectId}",
  "is_pinned": true
}

Endpoint parameters

Type	Name	Required	Notes
Path	`projectID`	Yes	Project identifier.
Body	`is_pinned`	Yes	Pins or unpins the project for the currently authenticated workspace member.

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/info" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "is_pinned": true
  }'

Example response

{
  "id": "{wsMemberId}",
  "project_id": "{projectId}",
  "is_pinned": true
}

Project-scoped chat

Use the current POST /api/v1/app/chat with project_id in the body. The compatibility URL POST /api/v1/app/project/{projectID}/chat remains available; migrate new clients to the current route. The current route always returns SSE.

Endpoint parameters

Type	Name	Required	Notes
Body	`project_id`	Yes	Project whose context is used.
Body	`pgpt`	Yes	Messages request containing exactly one user message.
Body	`artifacts`	No	Scoped artifact selectors.

curl -N -X POST "https://{BASE_URL}/api/v1/app/chat" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "artifacts": {
      "document": [
        {
          "scope": "project",
          "all_artifacts": true
        }
      ]
    },
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "Summarize the latest support trends in three bullets."
            }
          ]
        }
      ],
      "max_tokens": 80,
      "temperature": 0.2
    }
  }'

See Chats for SSE events and the complete body and artifact selection models. The legacy project URL honors pgpt.stream: true streams events; false returns a Message response.

Errors and edge cases

403: not a project member.
404: project not found.
409: transfer target not eligible.

First Steps

Build with Zylon

Coding Agents

Basic request and response

Project response fields

Get a project

Update a project

Delete a project

Leave a project

Transfer project ownership

Project workspace member info

Project-scoped chat

Errors and edge cases

​Basic request and response

​Project response fields

​Get a project

​Update a project

​Delete a project

​Leave a project

​Transfer project ownership

​Project workspace member info

​Project-scoped chat

​Errors and edge cases

Basic request and response

Project response fields

Get a project

Update a project

Delete a project

Leave a project

Transfer project ownership

Project workspace member info

Project-scoped chat

Errors and edge cases