> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/native-object-registry-api.md).

# Native Object Registry API

Read and manage Object Type definitions, Actions, Triggers, and versions from code.

The Native Object Registry API manages your tenant's [Object Type](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types.md) definitions: their data schemas, [Actions](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types/object-type-details/actions.md), [Triggers](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types/object-type-details/triggers.md), and [versions](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types/object-type-details/versions.md). Use it from scripts and backend services that read or change the structure of your data. For example, a deployment script can create or update Object Types.

To work with Records or run Actions, use the [Native Object API](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/native-object-api.md). In the Admin Console, you manage definitions under **Build > Object Types**. The CLI's `ctxl types` and `ctxl typeversions` commands also use this API to read and change definitions and to compare or roll back their versions.

## What you can do

* List Object Types and read a definition, including its data schema.
* Create, change, and delete Object Types.
* Add, change, and remove an Object Type's Actions and Triggers.
* List and read definition versions, and roll back to an earlier version.

## Base URL and reference

* **API base URL:** `https://native-object-registry.<tenant-id>.my.contextual.io/api/v1`
* **Swagger reference:** [Native Object Registry API reference](https://native-object-registry.prod-001.prod.contextual.io/api-docs/)
* **Raw OpenAPI:** [openapi.json](https://native-object-registry.prod-001.prod.contextual.io/api-docs/openapi.json)

Replace `<tenant-id>` with the [tenant ID from your Tenant Workspace URL](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#identify-the-tenant). On the API base URL, the hostname identifies your tenant, so the `x-org-id` header is optional.

The OpenAPI document uses the relative server `/api/v1`. When you import it into an API client or AI tool, set the server to the API base URL.

## Authentication and permissions

Send an access token from a tenant API Key in the `Authorization: Bearer <access-token>` header. To get one, follow [Get an access token](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#get-and-use-an-access-token), which also explains when you can reuse a token with other APIs.

Set the key's permissions on its [Permissions tab](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#assign-permissions). Those settings also apply to this API.

| Task                                                                               | Required permission                                                                                             |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| List Object Types, or read a definition and its Actions                            | **Service components → Object Types → Read**, or **Object data & action execution → Read** for that Object Type |
| Read Triggers or versions                                                          | **Service components → Object Types → Read**                                                                    |
| Create an Object Type, Action, or Trigger                                          | **Service components → Object Types → Create**                                                                  |
| Change an Object Type, Action, or Trigger, or roll back to a version               | **Service components → Object Types → Update**                                                                  |
| Delete an Object Type, Action, or Trigger, or delete all Records of an Object Type | **Service components → Object Types → Delete**                                                                  |

Object data & action execution permissions alone do not allow changes to definitions. For ordinary tenant callers, `GET /types` returns custom Object Type definitions and can filter the results by the caller's permissions.

Grant the delete permission with care. Deleting an Object Type, or all of its Records, cannot be undone.

## Request and response details

* Request and response bodies are JSON. Each definition's `_metaData` includes its `id`, `version`, and `hash`.
* List responses return results in `items`. To get the next page, send the returned `nextPageToken` as `pageToken`. Continue until a response has no `nextPageToken`, even if `items` is empty. Use `pageSize` to set the page size. To get `totalCount`, add `includeTotal=true` to a request without `pageToken`.
* Operations that change, delete, or roll back an existing definition, including its Actions and Triggers, accept an optional `x-if-hash-match` header. The reference shows which operations accept it. Set it to the `_metaData.hash` you last read. For an Action or Trigger, use the `_metaData.hash` of its Object Type definition. If the definition has changed since then, the API returns `412`. Read the definition again and reconcile the changes before you retry.
* When you form a request, replace `[\$]` in a reference path with a literal `$`. For example, `/[\$]page/types` becomes `/$page/types`. In a shell command, put a URL that contains `$page` in single quotes, or write `\$page`, so that the shell doesn't replace `$page` with a variable's value.

## Example request

This request lists up to 10 Object Types:

```bash
curl "https://native-object-registry.<tenant-id>.my.contextual.io/api/v1/types?pageSize=10" \
  --header "Authorization: Bearer <access-token>"
```

Replace `<access-token>` with your access token. A successful response has status `200` and up to 10 definitions in `items`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/native-object-registry-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
