Projects

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