About the Projects API

Developer Preview
APIs in Developer Preview are subject to change and are not intended for use in production.
Send us your suggestions for improving this API. Your feedback is valuable to us.

 

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:

  • Create, update, and delete projects.
  • Retrieve, list, and query projects.
  • Listen for events when a project is created, updated, and deleted.

Before you begin

It’s important to note the following points before starting to code:

  • To add or update a cover image or video for projects, first upload the media file to the Wix Media Manager by calling the Import File method.
  • You can only use this API on sites where a Wix user has installed the Wix Portfolio app.

Use cases

Did this help?

Sample Use Cases and Flows

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.

Delete residential building projects older than 2 years

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.

  1. Call Create Projects to create a project for each residential building available for investment.

  2. 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.

  3. 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.

  1. Wix users can create and manage projects in a Wix Portfolio.

  2. 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.

  3. Reflect the changes in your gallery.

Did this help?

Projects: Supported Filters and Sorting

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:

FieldSupported FiltersSortable
ideq, ne, exists, in, hasSome, startsWith, ascending, descendingSortable
titleeq, ne, exists, in, hasSome, startsWith, ascending, descendingSortable
descriptioneq, ne, exists, in, hasSome, startsWith, ascending, descendingSortable
slugeq, ne, exists, in, hasSome, startsWith, ascending, descendingSortable
hiddeneq, ne, exists, in, hasSome, startsWith, ascending, descending
collectionIdseq, ne, exists, in, hasSome, startsWith, ascending, descending
createdDateeq, ne, exists, in, hasSome, startsWith, ascending, descendingSortable
updatedDateeq, ne, exists, in, hasSome, startsWith, ascending, descendingSortable
Did this help?

Project Object


Properties
idstringRead-onlyformat GUID

Project ID.


revisionintegerRead-onlyformat uint64

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.


titlestringmaxLength 100

Project title.


descriptionstring

Project description.


hiddenboolean

Whether the project is hidden from the portfolio. Default: false


collectionIdsArray <string>format GUIDmaxItems 1000

IDs of the collections that include the project.


detailsArray <ProjectDetail>

Project details.


slugstring

Project slug.


createdDatestringRead-onlyformat date-time

Date and time the project was created.


updatedDatestringRead-onlyformat date-time

Date and time the project was updated.


urlUrlRead-only

Project page URL and and relative path. Returned when includePageUrl is true in the request.


seoDataSeoData

Project SEO data.


ONE OF:

coverImageCoverImage

Project cover image.


coverVideoCoverVideo

Project cover video.

Project
JSON
{ "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" } }
Did this help?

GET

List Projects


Developer Preview

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.

Permissions
Manage Portfolio
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/portfolio/v1/projects

Query Params
paging.limitintegerminimum 0maximum 100format int32

Maximum number of items to return in the results.


paging.cursorstringmaxLength 16000

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.


includePageUrlboolean

Whether to include the project's relative path and full URL in the response. Default: false

Response Object
projectsArray <Project>

List of projects.


metadataMetadata

Paging metadata.

List Projects
Request
cURL
curl -X GET \ 'https://www.wixapis.com/api/v1/portfolio/projects' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \
Response
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" } } }
Did this help?

POST

Create Project


Developer Preview

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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Portfolio
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/portfolio/v1/projects

Body Params
projectProjectRequired

Project to create.

Response Object
projectProject

Created project.

Create Project
Request
cURL
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", } }, } }'
Response
JSON
{ "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" } ] } } }
Event TriggersThis method triggers the following events:
Did this help?

GET

Get Project


Developer Preview

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.

Permissions
Manage Portfolio
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/portfolio/v1/projects/{projectId}

Path Params
projectIdstringRequired

ID of the project to retrieve.

Query Params
includePageUrlboolean

Whether to include the project's relative path and full URL in the response. Default: false

Response Object
projectProject

The requested project.

Get Project
Request
cURL
curl -X GET \ 'https://www.wixapis.com/api/v1/portfolio/projects/123e4567-e89b-12d3-a456-426614174000?includePageUrl=true' \ -H 'Authorization: <AUTH>' \
Response
JSON
{ "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" } ] } } }
Did this help?

DELETE

Delete Project


Developer Preview

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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Portfolio
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/portfolio/v1/projects/{projectId}

Path Params
projectIdstringRequired

ID of the project to delete.

Response Object
projectIdstringformat GUID

ID of the deleted project.

Delete Project
Request
cURL
curl -X DELETE \ 'https://www.wixapis.com/api/v1/portfolio/projects/c68c0dc5-088f-4205-b202-3eef797ea0ab' \ -H 'Authorization: <AUTH>' \
Response
JSON
{ "projectId": "c68c0dc5-088f-4205-b202-3eef797ea0ab" }
Event TriggersThis method triggers the following events:
Did this help?

PATCH

Update Project


Developer Preview

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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Portfolio
Learn more about app permissions.
Endpoint
PATCH
https://www.wixapis.com/portfolio/v1/projects/{project.id}

Path Params
project.idstringRequired

Project ID.

Body Params
projectProjectRequired

Project to update.

Response Object
projectProject

Updated project.

Update Project
Request
cURL
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" } }'
Response
JSON
{ "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" } ] } } }
Event TriggersThis method triggers the following events:
Did this help?

POST

Query Projects


Developer Preview

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.

Permissions
Manage Portfolio
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/portfolio/v1/projects/query

Body Params
queryQueryRequired

Query options.


includePageUrlboolean

Whether to include the project's relative path and full URL in the response. Default: false

Response Object
projectsArray <Project>

List of projects.


metadataMetadata

Paging metadata.

Query Projects
Request
cURL
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 }'
Response
JSON
{ "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" } } }
Did this help?

Project Created


Developer Preview

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.

Permissions
Manage Portfolio
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.portfolio.projects.v1.project.


slugstring

Event name. Expected created.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


createdEventCreatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "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 } } }
Did this help?

Project Deleted


Developer Preview

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.

Permissions
Manage Portfolio
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.portfolio.projects.v1.project.


slugstring

Event name. Expected deleted.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


deletedEventstruct

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "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 } } }
Did this help?

Project Updated


Developer Preview

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.

Permissions
Manage Portfolio
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.portfolio.projects.v1.project.


slugstring

Event name. Expected updated.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


updatedEventUpdatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "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 } } }
Did this help?