Get Schema

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

import requests

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

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/{schemaId}', 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/{schemaId}",
  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/{schemaId}"

	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/{schemaId}")

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

{
  "schemaId": "<string>",
  "name": "<string>",
  "description": "<string>",
  "businessAreaId": "<string>",
  "businessAreaName": "<string>",
  "version": 123,
  "createdBy": "<string>",
  "updatedBy": "<string>",
  "createdDate": "<string>",
  "updatedDate": "<string>",
  "fields": [
    {
      "fieldId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "active": true,
      "dataType": "<string>",
      "isPrimaryKey": true,
      "isSortKey": true,
      "isRequired": true,
      "isMultivalue": true,
      "isPII": true,
      "min": {},
      "max": {},
      "classifiers": [
        {
          "tagId": "<string>",
          "tagName": "<string>"
        }
      ],
      "validationRules": [
        {}
      ],
      "allowedBooleanValues": "<string>",
      "picklistType": "<string>",
      "staticPicklist": [
        {
          "code": "<string>",
          "description": "<string>"
        }
      ],
      "dataDomainId": "<string>",
      "dateFormat": "<string>",
      "dateSeparator": "<string>",
      "timeFormat": "<string>",
      "maxWidth": 123,
      "maxHeight": 123,
      "maxSize": 123,
      "createdBy": "<string>",
      "updatedBy": "<string>",
      "createdDate": "<string>",
      "updatedDate": "<string>"
    }
  ]
}

GET

businessareas

{businessAreaId}

schemas

{schemaId}

Get Schema

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

import requests

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

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/{schemaId}', 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/{schemaId}",
  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/{schemaId}"

	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/{schemaId}")

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

{
  "schemaId": "<string>",
  "name": "<string>",
  "description": "<string>",
  "businessAreaId": "<string>",
  "businessAreaName": "<string>",
  "version": 123,
  "createdBy": "<string>",
  "updatedBy": "<string>",
  "createdDate": "<string>",
  "updatedDate": "<string>",
  "fields": [
    {
      "fieldId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "active": true,
      "dataType": "<string>",
      "isPrimaryKey": true,
      "isSortKey": true,
      "isRequired": true,
      "isMultivalue": true,
      "isPII": true,
      "min": {},
      "max": {},
      "classifiers": [
        {
          "tagId": "<string>",
          "tagName": "<string>"
        }
      ],
      "validationRules": [
        {}
      ],
      "allowedBooleanValues": "<string>",
      "picklistType": "<string>",
      "staticPicklist": [
        {
          "code": "<string>",
          "description": "<string>"
        }
      ],
      "dataDomainId": "<string>",
      "dateFormat": "<string>",
      "dateSeparator": "<string>",
      "timeFormat": "<string>",
      "maxWidth": 123,
      "maxHeight": 123,
      "maxSize": 123,
      "createdBy": "<string>",
      "updatedBy": "<string>",
      "createdDate": "<string>",
      "updatedDate": "<string>"
    }
  ]
}

The Get Schema endpoint returns detailed information about a specific schema within a business area, including its field definitions and validation rules.

Prerequisites

A Pretectum API key (see API Keys)
Permission to access schemas in your tenant
Valid business area ID and schema ID

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 containing the schema.

string

required

The unique identifier of the schema to retrieve. You can obtain this from the List Schemas endpoint.

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

curl -X GET "https://api.pretectum.io/v1/businessareas/20240115103000123a1b2c3d4e5f6789012345678901234/schemas/20240115103000456d1e2f3a4b5c6789012345678901234" \
  -H "Authorization: pre_your_api_key" \
  -H "Accept: application/json"

const apiKey = 'pre_your_api_key';

async function getSchema(businessAreaId, schemaId) {
  const response = await fetch(
    `https://api.pretectum.io/v1/businessareas/${businessAreaId}/schemas/${schemaId}`,
    {
      headers: {
        'Authorization': apiKey,
        'Accept': 'application/json'
      }
    }
  );

  if (!response.ok) {
    if (response.status === 404) {
      return null;
    }
    throw new Error(`Failed to fetch schema: ${response.statusText}`);
  }

  return response.json();
}

const schema = await getSchema('20240115103000123a1b2c3d4e5f6789012345678901234', '20240115103000456d1e2f3a4b5c6789012345678901234');
if (schema) {
  console.log(`Schema: ${schema.name}`);
  console.log(`Fields: ${schema.fields.length}`);
}

import requests

api_key = 'pre_your_api_key'

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

    if response.status_code == 404:
        return None

    response.raise_for_status()
    return response.json()

schema = get_schema('20240115103000123a1b2c3d4e5f6789012345678901234', '20240115103000456d1e2f3a4b5c6789012345678901234')
if schema:
    print(f"Schema: {schema['name']}")
    print(f"Fields: {len(schema['fields'])}")

Response

A successful request returns a schema object with its complete definition including field specifications.

string

required

The unique identifier for the schema.

string

required

The display name of the schema.

string

A description of the schema explaining its purpose.

string

required

The ID of the business area this schema belongs to.

string

required

The name of the business area this schema belongs to.

integer

The version number of the schema.

string

The email address of the user who created the schema.

string

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

string

required

The ISO 8601 timestamp when the schema was created.

string

The ISO 8601 timestamp when the schema was last modified.

array

required

An array of field definitions that make up the schema structure. Fields are ordered by creation date (ascending).

Show Field object properties

string

required

The unique identifier for the field.

string

required

The display name of the field. This is the attribute name used when searching data objects.

string

A description of the field and its purpose.

boolean

required

Whether the field is currently active.

string

required

The data type of the field. Possible values: integer, float, string, boolean, datetime, date, time, date-year, date-month, date-day, currency, picklist, email, url, phone, latlng, latitude, longitude, attachment, image, document, video.

boolean

required

Whether the field is a primary key for the data object.

boolean

required

Whether the field is used as a sort key.

boolean

required

Whether the field is required when creating or updating data objects.

boolean

Whether the field can contain multiple values.

boolean

Whether the field contains Personally Identifiable Information (PII).

number | string

Minimum value constraint for the field (applies to numeric, string length, or date fields).

number | string

Maximum value constraint for the field (applies to numeric, string length, or date fields).

array

Tags associated with the field for categorization.

Show Classifier properties

string

Tag identifier

string

Tag display name

array

Array of validation rule strings applied to the field (e.g., “alphanumeric”).

string

Format for boolean values. Only applies when dataType is boolean. Possible values: y/n, Y/N, 1/0, t/f, T/F.

string

Type of picklist. Only applies when dataType is picklist. Possible values: static, dynamic.

array

List of allowed values for static picklists. Only present when picklistType is static.

Show Picklist option properties

string

The value code

string

The display description

string

ID of the data domain for dynamic picklists. Only present when picklistType is dynamic.

string

Format for date values. Only applies when dataType is date or datetime. Possible values: DD$MM$YYYY, DD$MMM$YYYY, MM$DD$YYYY, MMM$DD$YYYY, MM$DD$YY, YYYY$MM$DD, YYYY$MMM$DD, YY$MM$DD, YYMMDD, YYYYMMDD.

string

Separator for date components. Possible values: -, /, ., (space).

string

Format for time values. Possible values: hh:mm:ss a, hh:mm:ss A, hh:mm a, hh:mm A, HH:mm:ss, HH:mm.

number

Maximum width in pixels for image and attachment types.

number

Maximum height in pixels for image and attachment types.

number

Maximum file size in bytes for attachment, image, document, and video types.

string

Email of the user who created the field.

string

Email of the user who last updated the field.

string

ISO 8601 timestamp when the field was created.

string

ISO 8601 timestamp when the field was last updated.

Example Response

{
  "schemaId": "20240115103000456d1e2f3a4b5c6789012345678901234",
  "name": "Customer Schema",
  "description": "Schema for customer data management",
  "businessAreaId": "20240115103000123a1b2c3d4e5f6789012345678901234",
  "businessAreaName": "Customer Management",
  "createdBy": "john.doe@example.com",
  "updatedBy": "jane.smith@example.com",
  "createdDate": "2025-01-15T10:30:00Z",
  "updatedDate": "2025-03-20T14:45:00Z",
  "version": 2,
  "fields": [
    {
      "fieldId": "20250115103500001a1b2c3d4e5f6789012345678901234",
      "name": "customer_id",
      "description": "Unique identifier for the customer",
      "active": true,
      "isPrimaryKey": true,
      "isSortKey": false,
      "dataType": "string",
      "max": 20,
      "min": 5,
      "isRequired": true,
      "isMultivalue": false,
      "isPII": false,
      "classifiers": [
        {
          "tagName": "Identifier",
          "tagId": "id-001"
        }
      ],
      "validationRules": ["alphanumeric"],
      "createdBy": "john.doe@example.com",
      "updatedBy": "john.doe@example.com",
      "createdDate": "2025-01-15T10:35:00Z",
      "updatedDate": "2025-01-15T10:35:00Z"
    },
    {
      "fieldId": "20250115103700002b2c3d4e5f6a7890123456789012345",
      "name": "full_name",
      "description": "Customer's full name",
      "active": true,
      "isPrimaryKey": false,
      "isSortKey": true,
      "dataType": "string",
      "max": 100,
      "min": 2,
      "isRequired": true,
      "isMultivalue": false,
      "isPII": true,
      "classifiers": [
        {
          "tagName": "Personally Identifiable",
          "tagId": "pii-001"
        }
      ],
      "validationRules": [],
      "createdBy": "john.doe@example.com",
      "updatedBy": "jane.smith@example.com",
      "createdDate": "2025-01-15T10:37:00Z",
      "updatedDate": "2025-02-20T11:22:00Z"
    },
    {
      "fieldId": "20250115104000003c3d4e5f6a7b8901234567890123456",
      "name": "date_of_birth",
      "description": "Customer's date of birth",
      "active": true,
      "isPrimaryKey": false,
      "isSortKey": false,
      "dataType": "date",
      "max": "2010-12-31",
      "min": "1920-01-01",
      "isRequired": false,
      "isMultivalue": false,
      "isPII": true,
      "dateFormat": "YYYY$MM$DD",
      "dateSeparator": "-",
      "classifiers": [
        {
          "tagName": "Personally Identifiable",
          "tagId": "pii-001"
        }
      ],
      "validationRules": [],
      "createdBy": "john.doe@example.com",
      "updatedBy": "john.doe@example.com",
      "createdDate": "2025-01-15T10:40:00Z",
      "updatedDate": "2025-01-15T10:40:00Z"
    },
    {
      "fieldId": "20250115104200004d4e5f6a7b8c9012345678901234567",
      "name": "customer_type",
      "description": "Type of customer",
      "active": true,
      "isPrimaryKey": false,
      "isSortKey": false,
      "dataType": "picklist",
      "isRequired": true,
      "isMultivalue": false,
      "isPII": false,
      "picklistType": "static",
      "staticPicklist": [
        {
          "code": "individual",
          "description": "Individual customer"
        },
        {
          "code": "corporate",
          "description": "Corporate customer"
        },
        {
          "code": "vip",
          "description": "VIP customer"
        }
      ],
      "classifiers": [],
      "validationRules": [],
      "createdBy": "john.doe@example.com",
      "updatedBy": "jane.smith@example.com",
      "createdDate": "2025-01-15T10:42:00Z",
      "updatedDate": "2025-03-10T09:15:00Z"
    },
    {
      "fieldId": "20250115104500005e5f6a7b8c9d0123456789012345678",
      "name": "is_active",
      "description": "Whether the customer account is active",
      "active": true,
      "isPrimaryKey": false,
      "isSortKey": false,
      "dataType": "boolean",
      "isRequired": true,
      "isMultivalue": false,
      "isPII": false,
      "allowedBooleanValues": "Y/N",
      "classifiers": [],
      "validationRules": [],
      "createdBy": "john.doe@example.com",
      "updatedBy": "john.doe@example.com",
      "createdDate": "2025-01-15T10:45:00Z",
      "updatedDate": "2025-01-15T10:45:00Z"
    },
    {
      "fieldId": "20250210132000006f6a7b8c9d0e1234567890123456789",
      "name": "profile_picture",
      "description": "Customer's profile picture",
      "active": true,
      "isPrimaryKey": false,
      "isSortKey": false,
      "dataType": "image",
      "isRequired": false,
      "isMultivalue": false,
      "isPII": true,
      "maxWidth": 1024,
      "maxHeight": 1024,
      "maxSize": 5242880,
      "classifiers": [
        {
          "tagName": "Personally Identifiable",
          "tagId": "pii-001"
        }
      ],
      "validationRules": [],
      "createdBy": "jane.smith@example.com",
      "updatedBy": "jane.smith@example.com",
      "createdDate": "2025-02-10T13:20:00Z",
      "updatedDate": "2025-02-10T13:20:00Z"
    }
  ]
}

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 this schema.
`404 Not Found`	The specified schema or business area does not exist, or you do not have access to it.
`500 Internal Server Error`	An unexpected error occurred on the server.

Use Cases

Understanding Data Structure

Use the schema details to understand what fields are available for searching:

const schema = await getSchema(businessAreaId, schemaId);

// Get searchable fields for building search queries
const searchableFields = schema.fields
  .filter(field => field.searchable)
  .map(field => field.name);

console.log('Searchable fields:', searchableFields);
// Output: ['First Name', 'Last Name', 'Email', 'Phone', 'Active']

Building Dynamic Forms

Use the field definitions to dynamically generate data entry forms:

const schema = await getSchema(businessAreaId, schemaId);

const formFields = schema.fields.map(field => ({
  name: field.name,
  type: mapDataTypeToInputType(field.dataType),
  required: field.required,
  placeholder: field.description
}));

Validating Data Before Search

Verify that a field exists and is searchable before including it in a query:

def is_field_searchable(schema, field_name):
    for field in schema['fields']:
        if field['name'] == field_name:
            return field.get('searchable', False)
    return False

schema = get_schema('20240115103000123a1b2c3d4e5f6789012345678901234', '20240115103000456d1e2f3a4b5c6789012345678901234')
if is_field_searchable(schema, 'Email'):
    # Safe to search by Email field
    results = search('email:*@example.com', schema='Individual Customer')

Best Practices

Cache schema definitions: Schema structures change infrequently. Cache them locally.
Check searchable flag: Only use fields marked as searchable: true in search queries.
Respect required fields: When building forms, ensure required fields are validated.
Use field names in queries: For field-specific searches, use the name property from field definitions.

List Schemas

Get all schemas in a business area

List Business Areas

Get business area IDs

Search Data Objects

Search using schema field names

API Keys

Obtain authentication token

Overview

Authentication

Business Areas

Schemas

Datasets

Data Objects

Get Schema

Prerequisites

Authentication

Request

Path Parameters

Headers

Example Requests

Response

Example Response

Error Responses

Use Cases

Understanding Data Structure

Building Dynamic Forms

Validating Data Before Search

Best Practices

List Schemas

List Business Areas

Search Data Objects

API Keys

​Prerequisites

​Authentication

​Request

​Path Parameters

​Headers

​Example Requests

​Response

​Example Response

​Error Responses

​Use Cases

​Understanding Data Structure

​Building Dynamic Forms

​Validating Data Before Search

​Best Practices

​Related Endpoints

List Schemas

List Business Areas

Search Data Objects

API Keys

Prerequisites

Authentication

Request

Path Parameters

Headers

Example Requests

Response

Example Response

Error Responses

Use Cases

Understanding Data Structure

Building Dynamic Forms

Validating Data Before Search

Best Practices

Related Endpoints