> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Pages

The Pages API lets you manage pages and widgets in your Port portal programmatically. You can create, update, delete, and get pages, manage widgets, and update page permissions.

Improved Pages API now in GA

Port has released an improved version of the Pages API. This version is more reliable, secure, and intuitive, with stronger validations and clearer error messages. Once your account is rolled out to this version, these updates apply both when you call the Pages API directly and when you manage pages through IaC.

Improvements​

The improved Pages API includes many changes. The following are examples, not a complete list:

  • Clearer, field-specific error messages. For example, sending "title": 2 in a POST widget body no longer returns a generic and inaccurate message like "widget" must have required property 'agentIdentifier'. Instead, you get a matching error such as "widget/title" Invalid input: expected string, received number.
  • Page type (for example "blueprint-entities", "dashboard", and others) is required when creating a page.
  • Stricter checks of page structure, including grouper and dashboard-widget widgets and their hierarchy with other widgets inside the page.
  • Added validations that enforce a better widget experience with fewer bugs. Missing required fields now return an error instead of creating a partially valid widget.
  • Full IaC support - including specific entity page.

Rollout​

Port has enabled the improved Pages API for accounts where all organizations under the account pass the new validations of the improved API with no errors.

In order to check whether an organization uses the beta version or GA version of the Pages API, call GET /pages/version.

How to move from beta to GA​

If the response shows the beta version, complete the following steps to move to the GA version with the API improvements:

  1. Use the pages validation script and run it as admin for all organizations in your account. The improved API is enabled at the account level, so all organizations must pass validation.
  2. If the script reports errors, you can run the fix script from the same repository. This script automatically fixes some of the reported errors and applies the changes to the pages in Port. When it finishes, you receive a report listing which pages were fixed and what change was applied to each one.
  3. Update any source that calls the Pages API (such as IaC, scripts, or other tooling) to match the fixes from the report, so your code stays in sync with the pages in Port.
  4. Re-run the validation script to see which errors remain. Fix the remaining errors on your own in any source that calls the Pages API, and apply the changes so the pages in Port are updated.
  5. Re-run the validation script until it returns an empty errors response for all organizations in your account.
  6. Call POST /pages/version/register to move to the improved GA version.
  7. Call GET /pages/version again to confirm that your organization is now on the GA version.
Fix validation errors with AI

If you do not manage pages with IaC, you can use Port AI or the Port MCP server to suggest a relevant fix according to the errors the validation script reports. Attach the errors from the validation script to your request, then ask your assistant to call the validate_page tool to diagnose page JSON against the improved Pages API schema and guardrails, and apply fixes iteratively. This workflow is much easier and smoother than manually interpreting validation errors.

Available endpoints​

The Swagger API documentation still matches the beta version of the Pages API. The API reference pages in these docs describe the new, improved Pages API.

The pages endpoints allow you to:

  • Create, update, delete, and get pages.
  • Create, update, and delete widgets.
  • Update and get page permissions.

Page types​

The Pages API works with the page types available in Port: