MetorialDocs

Portal Listings

Read the shared listings available on a portal surface.

The Portal Listing object

portal_listing.json
{
  "object": "consumer.access_listing",
  "id": "example_id",
  "name": "example_name",
  "description": "example_description",
  "readme": "example_readme",
  "access": {
    "type": "provider_template",
    "provider_template": {
      "object": "provider.template#preview",
      "id": "example_id",
      "status": "active",
      "name": "example_name",
      "description": "example_description",
      "metadata": {},
      "integration_id": "example_integration_id",
      "created_at": "2026-10-17T09:50:02.684Z",
      "updated_at": "2026-10-17T09:50:02.684Z"
    }
  },
  "groups": [
    {},
    {}
  ],
  "created_at": "2026-10-17T09:50:02.684Z",
  "updated_at": "2026-10-17T09:50:02.684Z"
}
object"consumer.access_listing"required
idstringrequired
namestringrequired
descriptionstringrequirednullable
readmestringrequirednullable
created_atdaterequired
updated_atdaterequired

Endpoints

Get portal listing

GET/portals/:portal_id/listings/:listing_id

Retrieves one shared listing for a portal.

Path parameters

portal_idstringrequired

The unique identifier for the portal

listing_idstringrequired

The unique identifier for the listing

Example request

curl -X GET "https://api.metorial.com/portals/por_Rm4Mnheq2bfEPhBhP7SY/listings/lis_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Create portal listing

POST/portals/:portal_id/listings

Creates a shared listing for a portal.

Path parameters

portal_idstringrequired

The unique identifier for the portal

Request body

namestringoptional
descriptionstringoptionalnullable
readmestringoptionalnullable

Example request

curl -X POST "https://api.metorial.com/portals/por_Rm4Mnheq2bfEPhBhP7SY/listings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "readme": "example_readme",
  "access": {
    "type": "provider_template",
    "provider_template_id": "example_provider_template_id"
  }
}'

Update portal listing

PATCH/portals/:portal_id/listings/:listing_id

Updates listing metadata for a portal listing.

Path parameters

portal_idstringrequired

The unique identifier for the portal

listing_idstringrequired

The unique identifier for the listing

Request body

namestringoptional
descriptionstringoptionalnullable
readmestringoptionalnullable

Example request

curl -X PATCH "https://api.metorial.com/portals/por_Rm4Mnheq2bfEPhBhP7SY/listings/lis_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "readme": "example_readme"
}'

Delete portal listing

DELETE/portals/:portal_id/listings/:listing_id

Deletes a portal listing and all consumer access attached to it.

Path parameters

portal_idstringrequired

The unique identifier for the portal

listing_idstringrequired

The unique identifier for the listing

Example request

curl -X DELETE "https://api.metorial.com/portals/por_Rm4Mnheq2bfEPhBhP7SY/listings/lis_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."