> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pretectum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Schemas

> Retrieve the list of schemas within a specific business area

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](/api-reference/authentication/api-keys))
* Permission to access schemas in your tenant
* Knowledge of the business area ID (see [List Business Areas](/api-reference/business-areas/list))

## Authentication

Include your API key in the `Authorization` header.

```bash theme={null}
Authorization: pre_your_api_key
```

## Request

### Path Parameters

<ParamField path="businessAreaId" type="string" required>
  The unique identifier of the business area to retrieve schemas from. You can obtain this from the [List Business Areas](/api-reference/business-areas/list) endpoint.
</ParamField>

### Query Parameters

<ParamField query="pageKey" type="string">
  A pagination token for retrieving the next page of results. This value is returned in the response when more results are available.
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required initialValue="pre_your_api_key">
  Your Pretectum API key. Create one in the Pretectum app under **Configuration → API Keys**.
</ParamField>

<ParamField header="Accept" type="string" default="application/json">
  The response content type. Currently only `application/json` is supported.
</ParamField>

### Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```

  ```javascript JavaScript theme={null}
  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}`);
  });
  ```

  ```python Python theme={null}
  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']}")
  ```
</CodeGroup>

## Response

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

<ResponseField name="items" type="array" required>
  An array of schema objects within the business area.

  <Expandable title="Schema object properties">
    <ResponseField name="schemaId" type="string">
      The unique identifier for the schema. Use this ID when retrieving schema details.
    </ResponseField>

    <ResponseField name="name" type="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.
    </ResponseField>

    <ResponseField name="description" type="string">
      A description of the schema explaining its purpose and the type of data it defines.
    </ResponseField>

    <ResponseField name="businessAreaId" type="string">
      The ID of the business area this schema belongs to.
    </ResponseField>

    <ResponseField name="businessAreaName" type="string">
      The name of the business area this schema belongs to.
    </ResponseField>

    <ResponseField name="active" type="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.
    </ResponseField>

    <ResponseField name="state" type="string">
      The current state of the schema. Possible values include `draft`, `published`, etc.
    </ResponseField>

    <ResponseField name="fieldsCount" type="integer">
      The number of fields defined in this schema.
    </ResponseField>

    <ResponseField name="dataSetCount" type="integer">
      The number of datasets associated with this schema.
    </ResponseField>

    <ResponseField name="version" type="integer">
      The version number of the schema. This increments each time the schema structure is modified.
    </ResponseField>

    <ResponseField name="createdBy" type="string">
      The identifier of the user who created the schema.
    </ResponseField>

    <ResponseField name="createdByEmail" type="string">
      The email address of the user who created the schema.
    </ResponseField>

    <ResponseField name="updatedBy" type="string">
      The identifier of the user who last modified the schema.
    </ResponseField>

    <ResponseField name="updatedByEmail" type="string">
      The email address of the user who last modified the schema.
    </ResponseField>

    <ResponseField name="createdDate" type="string">
      The ISO 8601 timestamp when the schema was created.
    </ResponseField>

    <ResponseField name="updatedDate" type="string">
      The ISO 8601 timestamp when the schema was last modified.
    </ResponseField>

    <ResponseField name="deleted" type="boolean">
      Indicates whether the schema has been marked as deleted.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextPageKey" type="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.
</ResponseField>

### Example Response

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

<CodeGroup>
  ```javascript JavaScript theme={null}
  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}`);
  ```

  ```python Python theme={null}
  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)}")
  ```
</CodeGroup>

## Use Cases

### Filtering Search Results by Schema

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

```bash theme={null}
# 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:

```javascript theme={null}
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

1. **Cache schema lists**: Schemas change infrequently. Cache the response and refresh periodically.
2. **Filter by active status**: Only show active schemas in user interfaces.
3. **Use names for search filters**: When filtering searches with the `schema` parameter, use the `name` field value, not the `schemaId`.
4. **Handle pagination**: Always check for `pageKey` in responses and fetch all pages if needed.
5. **Get business area ID first**: Use the [List Business Areas](/api-reference/business-areas/list) endpoint to obtain valid business area IDs.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Schema Details" icon="file-code" href="/api-reference/schemas/get">
    Get detailed information about a specific schema
  </Card>

  <Card title="List Business Areas" icon="building" href="/api-reference/business-areas/list">
    Get business area IDs for schema queries
  </Card>

  <Card title="Search Data Objects" icon="magnifying-glass" href="/api-reference/dataobjects/search">
    Search within specific schemas
  </Card>

  <Card title="API Keys" icon="key" href="/api-reference/authentication/api-keys">
    Obtain authentication token
  </Card>
</CardGroup>