List Schemas

The List Schemas endpoint returns all schemas defined within a specific business area. Schemas define the structure, fields, and validation rules for data objects in Pretectum.

Prerequisites

Valid access token (see Get Access Token)
Permission to access schemas in your tenant
Knowledge of the business area ID (see List Business Areas)

Authentication

Include your access token in the Authorization header.

Pass the token directly without the “Bearer” prefix.

Authorization: your_access_token

Request

Path Parameters

businessAreaId

string

required

The unique identifier of the business area to retrieve schemas from. You can obtain this from the List Business Areas endpoint.

Query Parameters

pageKey

string

A pagination token for retrieving the next page of results. This value is returned in the response when more results are available.

Headers

Authorization

string

required

Your access token obtained from the /v1/oauth2/token endpoint. Pass the token directly without the “Bearer” prefix.

string

default:"application/json"

The response content type. Currently only application/json is supported.

Example Requests

# List all schemas in a business area
curl -X GET "https://api.pretectum.io/v1/businessareas/20240115103000123a1b2c3d4e5f6789012345678901234/schemas" \
  -H "Authorization: your_access_token" \
  -H "Accept: application/json"

# Paginate through schemas
curl -X GET "https://api.pretectum.io/v1/businessareas/20240115103000123a1b2c3d4e5f6789012345678901234/schemas?pageKey=eyJsYXN0S2V5IjoiMTIzIn0" \
  -H "Authorization: your_access_token" \
  -H "Accept: application/json"

Response

A successful request returns an object containing an array of schemas and pagination information.

items

array

required

An array of schema objects within the business area.

Show Schema object properties

schemaId

string

The unique identifier for the schema. Use this ID when retrieving schema details.

name

string

The display name of the schema. This is the human-readable name you can use in the schema filter parameter when searching data objects.

description

string

A description of the schema explaining its purpose and the type of data it defines.

businessAreaId

string

The ID of the business area this schema belongs to.

businessAreaName

string

The name of the business area this schema belongs to.

active

boolean

Indicates whether the schema is currently active. Inactive schemas may still have associated data objects but are typically not used for new data entry.

state

string

The current state of the schema. Possible values include draft, published, etc.

fieldsCount

integer

The number of fields defined in this schema.

dataSetCount

integer

The number of datasets associated with this schema.

version

integer

The version number of the schema. This increments each time the schema structure is modified.

createdBy

string

The identifier of the user who created the schema.

createdByEmail

string

The email address of the user who created the schema.

updatedBy

string

The identifier of the user who last modified the schema.

updatedByEmail

string

The email address of the user who last modified the schema.

createdDate

string

The ISO 8601 timestamp when the schema was created.

updatedDate

string

The ISO 8601 timestamp when the schema was last modified.

deleted

boolean

Indicates whether the schema has been marked as deleted.

nextPageKey

string

A pagination token for retrieving the next page of results. If this field is present, more schemas are available. Pass this value as the pageKey query parameter in your next request.

Example Response

{
  "items": [
    {
      "schemaId": "20240115103000456d1e2f3a4b5c6789012345678901234",
      "name": "Individual Customer",
      "description": "Schema for individual customer records with personal information",
      "businessAreaId": "20240115103000123a1b2c3d4e5f6789012345678901234",
      "businessAreaName": "Customer",
      "active": true,
      "state": "published",
      "fieldsCount": 12,
      "dataSetCount": 3,
      "version": 5,
      "createdBy": "30b6ed7f-3eff-4b3e-9dc5-0af48ee0058d",
      "createdByEmail": "[email protected]",
      "updatedBy": "45c7fe8g-4fgg-5c4f-0ed6-1bg59ff1169e",
      "updatedByEmail": "[email protected]",
      "createdDate": "2024-01-15T10:30:00Z",
      "updatedDate": "2024-06-15T14:22:00Z",
      "runningJobsCount": 0,
      "deleted": false
    },
    {
      "schemaId": "20240120090000789e2f3a4b5c6d7890123456789012345",
      "name": "Business Customer",
      "description": "Schema for business and corporate customer records",
      "businessAreaId": "20240115103000123a1b2c3d4e5f6789012345678901234",
      "businessAreaName": "Customer",
      "active": true,
      "state": "published",
      "fieldsCount": 15,
      "dataSetCount": 2,
      "version": 3,
      "createdBy": "30b6ed7f-3eff-4b3e-9dc5-0af48ee0058d",
      "createdByEmail": "[email protected]",
      "updatedBy": "30b6ed7f-3eff-4b3e-9dc5-0af48ee0058d",
      "updatedByEmail": "[email protected]",
      "createdDate": "2024-01-20T09:00:00Z",
      "updatedDate": "2024-05-10T11:30:00Z",
      "runningJobsCount": 0,
      "deleted": false
    }
  ],
  "nextPageKey": "eyJMYXN0RXZhbHVhdGVkS2V5Ijp7InNjaGVtYUlkIjoiOVZ6WmVJN25xS3ZLUE..."
}

Response Without Pagination

When all schemas fit in a single response, no nextPageKey is returned:

{
  "items": [
    {
      "schemaId": "20240115103000456d1e2f3a4b5c6789012345678901234",
      "name": "Individual Customer",
      "description": "Schema for individual customer records",
      "businessAreaId": "20240115103000123a1b2c3d4e5f6789012345678901234",
      "businessAreaName": "Customer",
      "active": true,
      "state": "published",
      "fieldsCount": 12,
      "dataSetCount": 3,
      "version": 5,
      "createdBy": "30b6ed7f-3eff-4b3e-9dc5-0af48ee0058d",
      "createdByEmail": "[email protected]",
      "updatedBy": "30b6ed7f-3eff-4b3e-9dc5-0af48ee0058d",
      "updatedByEmail": "[email protected]",
      "createdDate": "2024-01-15T10:30:00Z",
      "updatedDate": "2024-06-15T14:22:00Z",
      "runningJobsCount": 0,
      "deleted": false
    }
  ]
}

Empty Response

If the business area has no schemas defined, the response will contain an empty items array:

{
  "items": []
}

Error Responses

Status Code	Description
`401 Unauthorized`	Invalid or expired access token. Obtain a new token from `/v1/oauth2/token` and try again.
`403 Forbidden`	Your application client does not have permission to access schemas. Contact your tenant administrator.
`404 Not Found`	The specified business area does not exist or you do not have access to it.
`500 Internal Server Error`	An unexpected error occurred on the server. Try again later or contact support.

Pagination

When a business area contains many schemas, results are paginated. Use the nextPageKey from the response to fetch subsequent pages:

async function getAllSchemas(businessAreaId) {
  const allSchemas = [];
  let pageKey = null;

  do {
    const response = await getSchemas(businessAreaId, pageKey);
    allSchemas.push(...response.items);
    pageKey = response.nextPageKey;
  } while (pageKey);

  return allSchemas;
}

const allSchemas = await getAllSchemas('20240115103000123a1b2c3d4e5f6789012345678901234');
console.log(`Total schemas: ${allSchemas.length}`);

Use Cases

Filtering Search Results by Schema

Use the schema names returned by this endpoint to filter your data object searches:

# First, get the list of schemas
curl -X GET "https://api.pretectum.io/v1/businessareas/20240115103000123a1b2c3d4e5f6789012345678901234/schemas" \
  -H "Authorization: your_access_token"

# Then search within a specific schema
curl -X GET "https://api.pretectum.io/dataobjects/search?query=John&businessArea=Customer&schema=Individual%20Customer" \
  -H "Authorization: your_access_token"

Building Dynamic Filter UI

Populate dropdown menus with available schemas for a selected business area:

async function updateSchemaDropdown(businessAreaId) {
  const response = await getSchemas(businessAreaId);

  const options = response.items
    .filter(schema => schema.active)
    .map(schema => ({
      value: schema.name,
      label: schema.name,
      description: schema.description
    }));

  return options;
}

Best Practices

Cache schema lists: Schemas change infrequently. Cache the response and refresh periodically.
Filter by active status: Only show active schemas in user interfaces.
Use names for search filters: When filtering searches with the schema parameter, use the name field value, not the schemaId.
Handle pagination: Always check for pageKey in responses and fetch all pages if needed.
Get business area ID first: Use the List Business Areas endpoint to obtain valid business area IDs.

Get Schema Details

Get detailed information about a specific schema

List Business Areas

Get business area IDs for schema queries

Search Data Objects

Search within specific schemas

Get Access Token

Obtain authentication token

Overview

Authentication

Business Areas

Schemas

Datasets

Data Objects

Prerequisites

Authentication

Request

Path Parameters

Query Parameters

Headers

Example Requests

Response

Example Response

Empty Response

Error Responses

Use Cases

Filtering Search Results by Schema

Building Dynamic Filter UI

Best Practices

Get Schema Details

List Business Areas

Search Data Objects

Get Access Token

Overview

Authentication

Business Areas

Schemas

Datasets

Data Objects

​Prerequisites

​Authentication

​Request

​Path Parameters

​Query Parameters

​Headers

​Example Requests

​Response

​Example Response

​Response Without Pagination

​Empty Response

​Error Responses

​Pagination

​Use Cases

​Filtering Search Results by Schema

​Building Dynamic Filter UI

​Best Practices

​Related Endpoints

Get Schema Details

List Business Areas

Search Data Objects

Get Access Token

Prerequisites

Authentication

Request

Path Parameters

Query Parameters

Headers

Example Requests

Response

Example Response

Response Without Pagination

Empty Response

Error Responses

Pagination

Use Cases

Filtering Search Results by Schema

Building Dynamic Filter UI

Best Practices

Related Endpoints