The Projects API allows you to manage projects in a site's portfolio. Learn more about projects in Wix Portfolio.
With the Projects API, you can:
It’s important to note the following points before starting to code:
This article presents possible use cases and corresponding sample flows that you can support. This can be a helpful jumping off point as you plan your implementation.
You can integrate with the Projects API to display residential building projects available for investment. To keep listings current, once a year you might want to delete projects that are over 2 years old.
Call Create Projects to create a project for each residential building available for investment.
Once a year, call Query Projects using the created date property to retrieve all projects in the site's portfolio older than 2 years. Record the returned project IDs.
For each project ID returned, call Delete Project to remove the project from the portfolio.
You can create a curated art gallery that lists various artists' projects. To display the most up-to-date projects from your artists, set the gallery to automatically fetch and display projects whenever Wix users add, update, or delete them.
Wix users can create and manage projects in a Wix Portfolio.
Listen for the Project Created, Project Updated, and Project Deleted events to detect when projects have been added, updated, or deleted. Retrieve the latest project data from the event object.
Reflect the changes in your gallery.
This article covers field support for filtering and sorting in the Projects API.
The following table shows field support for filters and sorting for the projects object when calling Query Projects:
Field | Supported Filters | Sortable |
---|---|---|
id | eq , ne , exists , in , hasSome , startsWith , ascending , descending | Sortable |
title | eq , ne , exists , in , hasSome , startsWith , ascending , descending | Sortable |
description | eq , ne , exists , in , hasSome , startsWith , ascending , descending | Sortable |
slug | eq , ne , exists , in , hasSome , startsWith , ascending , descending | Sortable |
hidden | eq , ne , exists , in , hasSome , startsWith , ascending , descending | |
collectionIds | eq , ne , exists , in , hasSome , startsWith , ascending , descending | |
createdDate | eq , ne , exists , in , hasSome , startsWith , ascending , descending | Sortable |
updatedDate | eq , ne , exists , in , hasSome , startsWith , ascending , descending | Sortable |
Project ID.
Revision number, which increments by 1 each time the project is updated. To prevent conflicting changes, the existing revision must be passed when updating the project object.
Project title.
Project description.
Whether the project is hidden from the portfolio. Default: false
IDs of the collections that include the project.
Project details.
Project slug.
Date and time the project was created.
Date and time the project was updated.
Project page URL and and relative path. Returned when includePageUrl
is true
in the request.
Project SEO data.
Project cover image.
Project cover video.
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 5,
"title": "Sample Project",
"description": "This is a sample description for the project.",
"hidden": false,
"coverImage": {
"imageInfo": {
"id": "64c4566-e87b-77d3-a456-4266141779902",
"url": "https://example.com/cover.jpg",
"altText": "Project cover image"
}
},
"collectionIds": [
"123e4567-e89b-12d3-a456-426614174001",
"123e4567-e89b-12d3-a456-426614174002"
],
"details": [
{
"label": "GitHub",
"link": {
"text": "View on GitHub",
"url": "https://github.com/example/project",
"target": "_blank"
}
},
{
"label": "Description",
"text": "A detailed description of the project."
}
],
"slug": "sample-project",
"createdDate": "2024-07-31T12:00:00Z",
"updatedDate": "2024-07-31T12:00:00Z",
"url": {
"relativePath": "/project/sample-project",
"url": "https://portfolio.com/project/sample-project"
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a list of all projects in a portfolio.
Maximum number of items to return in the results.
Pointer to the next or previous page in the list of results.
Pass the relevant cursor token from the pagingMetadata
object in the previous call's response.
Not relevant for the first request.
Whether to include the project's relative path and full URL in the response. Default: false
List of projects.
Paging metadata.
curl -X GET \
'https://www.wixapis.com/api/v1/portfolio/projects' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
{
"projects": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 1,
"title": "Project Title",
"description": "Project Description",
"hidden": false,
"coverImage": {
"imageInfo": {
"id": "72144e4567-e89b-12d3-a456-426619234",
"url": "https://example.com/image-10.jpg",
}
},
"collectionIds": ["123e4567-e89b-12d3-a456-426614174001"],
"details": [
"label": "text",
"text": "My project is in memory of Sally Lang."
],
"slug": "project-title",
"createdDate": "2024-07-31T12:00:00Z",
"updatedDate": "2024-07-31T12:00:00Z"
}
],
"metadata": {
"count": 1,
"offset": 0,
"total": 1,
"tooManyToCount": false,
"cursors": {
"next": "next_cursor",
"prev": "prev_cursor"
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a project.
You can only call this method when authenticated as a Wix app or Wix user identity.
Project to create.
Created project.
curl -X POST \
'https://www.wixapis.com/api/v1/portfolio/projects' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"project": {
"title": "Project Title",
"description": "This is a project description.",
"hidden": false,
"collectionIds": ["123e4567-e89b-12d3-a456-426614174001"],
"slug": "new-project-title",
"coverImage": {
"imageInfo": {
"id": "9ab44e4567-e89b-12d3-a456-4266141747",
"url": "https://example.com/cover_image.jpg",
}
},
}
}'
{
"project": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 1,
"title": "Project Title",
"description": "This is a project description.",
"hidden": false,
"collectionIds": ["123e4567-e89b-12d3-a456-426614174001"],
"slug": "new-project-title",
"coverImage": {
"imageInfo": {
"id": "9ab44e4567-e89b-12d3-a456-4266141747",
"url": "https://example.com/cover_image.jpg"
}
},
"createdDate": "2024-07-31T12:00:00Z",
"updatedDate": "2024-09-31T12:00:00Z",
"seoData": {
"settings": {
"keywords": [
{
"isMain": true,
"origin": "marketing-persona",
"term": "investment management"
}
],
"preventAutoRedirect": false
},
"tags": [
{
"children": "Investment Experts Share Growth Strategies",
"custom": false,
"disabled": false,
"type": "title"
},
{
"children": "",
"custom": false,
"disabled": false,
"props": {
"content": "Investment strategies explained by investment experts. Investment experts offer valuable insights for growth.",
"name": "description"
},
"type": "meta"
}
]
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a project.
ID of the project to retrieve.
Whether to include the project's relative path and full URL in the response. Default: false
The requested project.
curl -X GET \
'https://www.wixapis.com/api/v1/portfolio/projects/123e4567-e89b-12d3-a456-426614174000?includePageUrl=true' \
-H 'Authorization: <AUTH>' \
{
"project": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 1,
"title": "Project Title",
"description": "Project Description",
"hidden": false,
"coverImage": {
"imageInfo": {
"id": "72144e4567-e89b-12d3-a456-426619234",
"url": "https://example.com/image-10.jpg"
}
},
"collectionIds": ["123e4567-e89b-12d3-a456-426614174001"],
"details": [],
"slug": "project-title",
"createdDate": "2024-07-31T12:00:00Z",
"updatedDate": "2024-09-31T12:00:00Z",
"url": {
"relativePath": "/projects/project-title",
"url": "https://example.com/projects/project-title"
},
"seoData": {
"settings": {
"keywords": [
{
"isMain": true,
"origin": "marketing-persona",
"term": "investment management"
}
],
"preventAutoRedirect": false
},
"tags": [
{
"children": "Investment Experts Share Growth Strategies",
"custom": false,
"disabled": false,
"type": "title"
},
{
"children": "",
"custom": false,
"disabled": false,
"props": {
"content": "Investment strategies explained by investment experts. Investment experts offer valuable insights for growth.",
"name": "description"
},
"type": "meta"
}
]
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Deletes a project.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the project to delete.
ID of the deleted project.
curl -X DELETE \
'https://www.wixapis.com/api/v1/portfolio/projects/c68c0dc5-088f-4205-b202-3eef797ea0ab' \
-H 'Authorization: <AUTH>' \
{
"projectId": "c68c0dc5-088f-4205-b202-3eef797ea0ab"
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates a project.
You can only call this method when authenticated as a Wix app or Wix user identity.
Project ID.
Project to update.
Updated project.
curl -X PATCH \
'https://www.wixapis.com/api/v1/portfolio/projects/123e4567-e89b-12d3-a456-426614174000' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"project": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 1,
"title": "Updated Project Title",
"description": "This is an updated project description.",
"hidden": false,
"coverImage": {
"imageInfo": {
"id": "9ab44e4567-e89b-12d3-a456-4266141747",
"url": "https://example.com/updated_cover_image1.jpg"
}
},
"slug": "updated-project-title"
}
}'
{
"project": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 2,
"title": "Updated Project Title",
"description": "This is an updated project description.",
"hidden": false,
"coverImage": {
"imageInfo": {
"id": "9ab44e4567-e89b-12d3-a456-4266141747",
"url": "https://example.com/updated_cover_image1.jpg"
}
},
"collectionIds": ["123e4567-e89b-12d3-a456-426614174001"],
"slug": "updated-project-title",
"createdDate": "2024-07-31T12:00:00Z",
"updatedDate": "2024-09-31T12:30:00Z",
"url": {
"relativePath": "/projects/updated-project-title",
"url": "https://example.com/projects/updated-project-title"
},
"seoData": {
"settings": {
"keywords": [
{
"isMain": true,
"origin": "marketing-persona",
"term": "investment management"
}
],
"preventAutoRedirect": false
},
"tags": [
{
"children": "Investment Experts Share Growth Strategies",
"custom": false,
"disabled": false,
"type": "title"
},
{
"children": "",
"custom": false,
"disabled": false,
"props": {
"content": "Investment strategies explained by investment experts. Investment experts offer valuable insights for growth.",
"name": "description"
},
"type": "meta"
}
]
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a list of projects, given the provided paging, filtering, and sorting. Up to 100 projects can be returned per request.
The default sort
is id
in ASC
.
For a detailed list of supported operations, see Projects: Supported Filters and Sorting. To learn how to query projects, see API Query Language.
Query options.
Whether to include the project's relative path and full URL in the response. Default: false
List of projects.
Paging metadata.
curl -X POST \
'https://www.wixapis.com/api/v1/portfolio/projects/query' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"query": {
"filter": {
"title": {
"$contains": "Project"
}
},
"sort": [
{
"fieldName": "createdDate",
"order": "ASC"
}
],
"cursorPaging": {
"limit": 10
}
},
"includePageUrl": true
}'
{
"projects": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 1,
"title": "Project Title",
"description": "Project Description",
"hidden": false,
"coverImage": {
"imageInfo": {
"id": "9ab44e4567-e89b-12d3-a456-4266141747",
"url": "https://example.com/updated_cover_image1.jpg"
}
}
"collectionIds": ["123e4567-e89b-12d3-a456-426614174001"],
"slug": "project-title",
"details": [
"label": "link",
"link": {
"text": "Learn more about my project.",
"url": "www.my-project.com",
"target": "'_blank'"
}
],
"createdDate": "2024-07-31T12:00:00Z",
"updatedDate": "2024-07-31T12:00:00Z",
"url": {
"relative": "/projects/project-title",
"url": "https://example.com/projects/project-title"
}
}
],
"metadata": {
"count": 1,
"offset": 0,
"total": 1,
"tooManyToCount": false,
"cursors": {
"next": "next_cursor",
"prev": "prev_cursor"
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a project is created.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.portfolio.projects.v1.project
.
Event name. Expected created
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.portfolio.projects.v1.project_created",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a project is deleted.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.portfolio.projects.v1.project
.
Event name. Expected deleted
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.portfolio.projects.v1.project_deleted",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a project is updated.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.portfolio.projects.v1.project
.
Event name. Expected updated
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.portfolio.projects.v1.project_updated",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}