About the Project Items 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 Project Items API allows you to manage a project's items. Learn more about project items in Wix Portfolio.

With the Project Items API, you can:

  • Create, update, and delete project items.
  • Retrieve project items.
  • Duplicate project items from one project to another project.
  • Listen for events when a project item is created, updated, or deleted.

Before you begin

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

  • You need an existing project to create project items. If you don't already have one, call Create Project to create a project, and then call Create Project Item to create a project item.
  • Project items consist of images or videos. Before you create or update a project item with a new media file, 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 case

Did this help?

Sample Use Case and Flow

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.

Create a digital photo frame

You can display a live photo gallery on a digital photo frame, updating dynamically in real-time.

  1. Call Create Project to create a project that will act as the photo gallery, allowing you to store and manage photos represented as project items within the gallery.

  2. Share the newly created project's ID with those who need to access the gallery so they can add or remove photos from the digital photo frame.

  3. Listen for Project Item Created, Project Item Updated, and Project Item Deleted events to detect when new photos are added, existing photos are updated, or photos are removed from the gallery.

  4. Periodically call List Project Items to retrieve the latest gallery content and ensure the photo frame reflects real-time changes.

Did this help?

Project Item Object


Properties
projectIdstringformat GUID

Project ID.


idstringRead-onlyformat GUID

Project item ID.


sortOrdernumberformat double

Index that determines which position a project is displayed in the project.

Default: Epoch timestamp.


titlestring

Project item title.


descriptionstring

Project item description.


typestringRead-only

Project item data type.


createdDatestringRead-onlyformat date-time

Date and time the project item was created.


updatedDatestringRead-onlyformat date-time

Date and time the project item was last updated.


linkLink

Project item link.


ONE OF:

imageImage

Information about the Wix Media image.


videoVideo

Information about the Wix Media video.

Item
JSON
{ "projectId": "123e4567-e89b-12d3-a456-426614174000", "id": "987e6543-e21a-10d2-b987-426614176789", "sortOrder": 1694090400.0, "title": "Sample Project Item Title", "description": "This is a description for the sample project item.", "type": "IMAGE", "image": { "imageInfo": { "id": "987e6543-e21a-10d2-b987-426614176789", "url": "https://example.com/image.jpg", "width": 1920, "height": 1080 } }, "createdDate": "2024-07-31T12:00:00Z", "updatedDate": "2024-07-31T12:00:00Z", "link": { "text": "View Project", "url": "https://example.com/project", "target": "_blank" } }
Did this help?

POST

Create Project Item


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

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/Items

Body Params
itemItemRequired

Project item to create.

Response Object
itemItem

Newly created project item.

Create Project Item
Request
cURL
curl -X POST \ 'https://www.wixapis.com/portfolio/v1/Items' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "item": { "projectId": "123e4567-e89b-12d3-a456-426614174000", "sortOrder": 1.0, "title": "Lonely", "description": "This is the Lonely song image cover.", "image": { "imageInfo": { "id": "23ff-66b77-888aaf-9c45227e, } }, "link": { "text": "Listen to the song", "url": "https://lonely-song.com", "target": "_blank" } } }'
Response
JSON
{ "item": { "id": "456e7890-e89b-12d3-a456-426614174000", "projectId": "123e4567-e89b-12d3-a456-426614174000", "title": "Lonely", "description": "This is the Lonely song image cover.", "sortOrder": 1.0, "type": "IMAGE", "image": { "imageInfo": { "id": "23ff-66b77-888aaf-9c45227e" } }, "createdDate": "2024-07-31T12:00:00Z", "updatedDate": "2024-07-31T12:00:00Z", "link": { "text": "Listen to the song", "url": "https://lonely-song.com", "target": "_blank" } } }
Event TriggersThis method triggers the following events:
Did this help?

GET

Get Project Item


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

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

Path Params
itemIdstringRequired

Project item ID.

Response Object
itemItem

Project item.

Get Project Item
Request
cURL
curl -X GET \ 'https://www.wixapis.com/portfolio/v1/Items/456e7890-e89b-12d3-a456-426614174001' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json'
Response
JSON
{ "item": { "id": "456e7890-e89b-12d3-a456-426614174001", "projectId": "123e4567-e89b-12d3-a456-426614174000", "title": "Item Title 1", "description": "This is item description 1.", "sortOrder": 1.0, "type": "IMAGE", "image": { "imageInfo": { "url": "https://example.com/image1.jpg", "id": "3886bbcc7fb-66b77-888aaf-3c45227f" } }, "createdDate": "2024-07-31T12:00:00Z", "updatedDate": "2024-07-31T12:00:00Z", "link": { "text": "Visit Site 1", "url": "https://example.com", "target": "_blank" } } }
Did this help?

DELETE

Delete Project Item


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

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/Items/{itemId}

Path Params
itemIdstringRequired

ID of the project item to delete.

Response Object
projectIdstringformat GUID

Project ID.


itemIdstringformat GUID

ID of the deleted project item.

Delete Project Item
Request
cURL
curl -X DELETE \ 'https://www.wixapis.com/portfolio/v1/Items/456e7890-e89b-12d3-a456-426614174001' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json'
Response
JSON
{ "projectId": "123e4567-e89b-12d3-a456-426614174000", "itemId": "456e7890-e89b-12d3-a456-426614174001" }
Event TriggersThis method triggers the following events:
Did this help?

GET

List Project Items


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 project items in the specified project.

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

Path Params
projectIdstringRequired

Project ID.

Query Params
paging.limitintegerminimum 0format int32

Number of items to load.


paging.offsetintegerminimum 0format int32

Number of items to skip in the current sort order.

Response Object
itemsArray <Item>

Project items.


pagingMetadataV2PagingMetadataV2deprecated

metadataMetadata

Paging metadata.

List Project Items
Request
cURL
curl -X GET \ 'https://www.wixapis.com/portfolio/v1/projectItems/123e4567-e89b-12d3-a456-426614174000/items' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \
Response
JSON
{ "items": [ { "id": "456e7890-e89b-12d3-a456-426614174001", "projectId": "123e4567-e89b-12d3-a456-426614174000", "title": "Item Title 1", "description": "This is item description 1.", "sortOrder": 1.0, "type": "IMAGE", "image": { "imageInfo": { "url": "https://example.com/image1.jpg", "id": "4889bbcc7fb-66b77-888aaf-3c45227f" } }, "createdDate": "2024-07-31T12:00:00Z", "updatedDate": "2024-07-31T12:00:00Z", "link": { "text": "Visit Site 1", "url": "https://example.com", "target": "_blank" } }, { "id": "456e7890-e89b-12d3-a456-426614174002", "projectId": "123e4567-e89b-12d3-a456-426614174000", "title": "Item Title 2", "description": "This is item description 2.", "sortOrder": 2.0, "type": "VIDEO", "video": { "videoInfo": { "url": "https://example.com/video3.mp4", "id": "4ee89bbcc7fb-69b77-888aaf-3c4522eec" } }, "createdDate": "2024-07-31T12:10:00Z", "updatedDate": "2024-07-31T12:10:00Z", "link": { "text": "Visit Site 2", "url": "https://example2.com", "target": "_self" } } ], "metadata": { "count": 2, "offset": 0, "total": 2, "tooManyToCount": false, "cursors": { "next": "next_cursor", "prev": "prev_cursor" } } }
Did this help?

PATCH

Update Project Item


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

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/Items/{item.id}

Path Params
item.idstringRequired

Project item ID.

Body Params
itemItemRequired

The project item to update.

Response Object
itemItem

The updated project item.

Update Project Item
Request
cURL
curl -X PATCH \ 'https://www.wixapis.com/portfolio/v1/Items/456e7890-e89b-12d3-a456-426614174001' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "item": { "title": "Updated Item Title", "description": "This is an updated item description.", "sortOrder": 1.0, "image": { "imageInfo": { "url": "https://example.com/new-image1.jpg", "id": "9a7eef_afc3d989928f45198a16175e3c7aba3d" } }, "link": { "text": "Visit Updated Site", "url": "https://example.com/update", "target": "_blank" } } }'
Response
JSON
{ "item": { "id": "456e7890-e89b-12d3-a456-426614174001", "projectId": "123e4567-e89b-12d3-a456-426614174000", "title": "Updated Item Title", "description": "This is an updated item description.", "sortOrder": 1.0, "type": "IMAGE", "image": { "imageInfo": { "url": "https://example.com/new-image1.jpg", "id": "9a7eef_afc3d989928f45198a16175e3c7aba3d" } }, "createdDate": "2024-07-31T12:00:00Z", "updatedDate": "2024-09-31T12:30:00Z", "link": { "text": "Visit Updated Site", "url": "https://example.com/update", "target": "_blank" } } }
Event TriggersThis method triggers the following events:
Did this help?

Project Item 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 item 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.project_items.v1.project_item.


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.project_items.v1.project_item_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 Item 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 item 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.project_items.v1.project_item.


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.project_items.v1.project_item_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 Item 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 item 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.project_items.v1.project_item.


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.project_items.v1.project_item_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?