List Schemas

curl --request GET \
  --url https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "schemaId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "businessAreaId": "<string>",
      "businessAreaName": "<string>",
      "active": true,
      "state": "<string>",
      "fieldsCount": 123,
      "dataSetCount": 123,
      "version": 123,
      "createdBy": "<string>",
      "createdByEmail": "<string>",
      "updatedBy": "<string>",
      "updatedByEmail": "<string>",
      "createdDate": "<string>",
      "updatedDate": "<string>",
      "deleted": true
    }
  ],
  "nextPageKey": "<string>"
}

GET

businessareas

{businessAreaId}

schemas

List Schemas

curl --request GET \
  --url https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "schemaId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "businessAreaId": "<string>",
      "businessAreaName": "<string>",
      "active": true,
      "state": "<string>",
      "fieldsCount": 123,
      "dataSetCount": 123,
      "version": 123,
      "createdBy": "<string>",
      "createdByEmail": "<string>",
      "updatedBy": "<string>",
      "updatedByEmail": "<string>",
      "createdDate": "<string>",
      "updatedDate": "<string>",
      "deleted": true
    }
  ],
  "nextPageKey": "<string>"
}

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

A Pretectum API key (see API Keys)
Permission to access schemas in your tenant
Knowledge of the business area ID (see List Business Areas)

Authentication

Include your API key in the Authorization header.

Authorization: pre_your_api_key

Request

Path Parameters

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

string

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

Headers

string

required

Your Pretectum API key. Create one in the Pretectum app under Configuration → API Keys.

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: pre_your_api_key" \
  -H "Accept: application/json"

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

const apiKey = 'pre_your_api_key';
const businessAreaId = '20240115103000123a1b2c3d4e5f6789012345678901234';

async function getSchemas(businessAreaId, pageKey = null) {
  const url = new URL(`https://api.pretectum.io/v1/businessareas/${businessAreaId}/schemas`);
  if (pageKey) {
    url.searchParams.set('pageKey', pageKey);
  }

  const response = await fetch(url, {
    headers: {
      'Authorization': apiKey,
      'Accept': 'application/json'
    }
  });

  return response.json();
}

const schemas = await getSchemas(businessAreaId);
console.log(`Found ${schemas.items.length} schemas`);
schemas.items.forEach(schema => {
  console.log(`- ${schema.name}: ${schema.description}`);
});

import requests

api_key = 'pre_your_api_key'
business_area_id = '20240115103000123a1b2c3d4e5f6789012345678901234'

def get_schemas(business_area_id, page_key=None):
    params = {}
    if page_key:
        params['pageKey'] = page_key

    response = requests.get(
        f'https://api.pretectum.io/v1/businessareas/{business_area_id}/schemas',
        params=params,
        headers={
            'Authorization': api_key,
            'Accept': 'application/json'
        }
    )
    response.raise_for_status()
    return response.json()

schemas = get_schemas(business_area_id)
print(f"Found {len(schemas['items'])} schemas")
for schema in schemas['items']:
    print(f"- {schema['name']}: {schema['description']}")

Response

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

array

required

An array of schema objects within the business area.

Show Schema object properties

string

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

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.

string

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

string

The ID of the business area this schema belongs to.

string

The name of the business area this schema belongs to.

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.

string

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

integer

The number of fields defined in this schema.

integer

The number of datasets associated with this schema.

integer

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

string

The identifier of the user who created the schema.

string

The email address of the user who created the schema.

string

The identifier of the user who last modified the schema.

string

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

string

The ISO 8601 timestamp when the schema was created.

string

The ISO 8601 timestamp when the schema was last modified.

boolean

Indicates whether the schema has been marked as deleted.

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": "admin@example.com",
      "updatedBy": "45c7fe8g-4fgg-5c4f-0ed6-1bg59ff1169e",
      "updatedByEmail": "data_architect@example.com",
      "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": "admin@example.com",
      "updatedBy": "30b6ed7f-3eff-4b3e-9dc5-0af48ee0058d",
      "updatedByEmail": "admin@example.com",
      "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": "admin@example.com",
      "updatedBy": "30b6ed7f-3eff-4b3e-9dc5-0af48ee0058d",
      "updatedByEmail": "admin@example.com",
      "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`	The API key is missing, malformed, unknown, inactive, expired or deleted. Check the key in Configuration → API Keys.
`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}`);

def get_all_schemas(business_area_id):
    all_schemas = []
    page_key = None

    while True:
        response = get_schemas(business_area_id, page_key)
        all_schemas.extend(response['items'])

        page_key = response.get('nextPageKey')
        if not page_key:
            break

    return all_schemas

all_schemas = get_all_schemas('20240115103000123a1b2c3d4e5f6789012345678901234')
print(f"Total schemas: {len(all_schemas)}")

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: pre_your_api_key"

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

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

API Keys

Obtain authentication token

Overview

Authentication

Business Areas

Schemas

Datasets

Data Objects

List Schemas

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

API Keys

​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

API Keys

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