> 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-api.md).

# Native Object API

Use the Native Object API to work with [Object Type](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types.md) Records and run [Actions](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types/object-type-details/actions.md) from your solution's code or other systems. The API is available when you create your tenant. Its endpoints and Swagger reference update automatically as you create or change Object Types and Actions. The CLI's `ctxl records` commands also use this API, for example to query Records or run an Action.

For API Key setup, access tokens, and permissions, see [Authentication and Permissions](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md).

## Your Native Object API Server Base URL

Your Native Object API base URL is `https://native-object.<tenant-id>.my.contextual.io/api/v1`. 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). You can also find the base URL in the [generated reference](#generated-reference-and-openapi).

## Generated Reference and OpenAPI

The generated reference describes your tenant's Record and Action operations, including their parameters, responses, and required scopes.

To open the reference, go to the Admin Console at `https://next.<tenant-id>.my.contextual.io`. In the navigation menu, under **Admin**, select **API Documentation**.

## Object Type Endpoints

Each Object Type has an endpoint that updates automatically when you change the Object Type. For example, a `customers` Object Type has the endpoint `https://native-object.<tenant-id>.my.contextual.io/api/v1/customers`.

## Object Type Endpoint Methods and Required Scope

Object Type endpoints support `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` methods. The generated reference describes each operation's purpose, required and optional parameters, response codes, and example schemas. Your API client needs the scope listed for the operation. For an API Key, grant the scope by setting its [permissions](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#assign-permissions).

For example, the scope `native-object:customers:read` is the **Read** action in the `customers` Object Type's row under **Object data & action execution**. It does not allow the create, update, delete, or execute actions. A `*` in place of the Object Type ID is the same action in the **All Object Types** row.

## Audit Trail Endpoint Methods and Required Scope

The Audit Trail endpoint supports `GET` and `POST` for an Object Type and for individual Records. The generated reference describes each operation and its required scope.

## Custom Headers

### `x-if-hash-match`

Use the optional `x-if-hash-match` header on a Record `PUT`, `PATCH`, or `DELETE` request to detect changes made by another caller since your last read. This helps you avoid editing or deleting a Record based on an outdated copy. The header applies to Object Types whose Records the platform stores.

Set the header to the Record's [`_metaData.hash`](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types/object-type-details/data-schema/automatic-metadata.md) from your last read:

```http
x-if-hash-match: <record-hash>
```

Copy the value as is. Don't compute it yourself, and don't use an Object Type definition hash from the [Native Object Registry API](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/native-object-registry-api.md).

If the hash no longer matches the Record, the API returns `412` and doesn't apply your change. Read the Record again, because it may have changed or been deleted. Decide whether your change still makes sense, and retry with the new hash only if it does. Don't resend the same change without checking.

Without the header, the API doesn't check whether the Record still matches your earlier read. Authentication, permissions, validation, and other checks still apply, so the request can still fail.

The header has no effect in these cases:

* External Object Types don't check it.
* Running an Action with `PATCH /{typeId}/{id}/actions/{actionId}` doesn't check it. Editing an Action definition in the Native Object Registry API is a separate operation that uses the Object Type definition hash.

Keep these limits in mind:

* A `412` means the API didn't apply your Record change. It doesn't mean nothing ran. Triggers that run before an update or delete, and other work before the final write, may already have run.
* Concurrent requests can still overlap without returning `412`. For example, two `PATCH` requests with the same hash can both apply because the data and hash are updated separately. Depending on the storage backend, a `DELETE` may also miss a change made after its hash check. Don't rely on this header to prevent every concurrent change.

## Notes

* **Security**: Handle your Client Secret with care. Consider a process to rotate it periodically to maintain security.
* **Permissions**: Review and adjust permissions regularly to ensure they align with your security policies and usage needs.


---

# 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-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.
