Publish ontology through API

Preview Publishing a logical model turns business concepts, such as customers, support cases, and the links between them, into one immutable ontology release that agents can query for bounded context. Use this recipe when agents need a governed, versioned definition of what your business terms mean, with a reviewable change trail. To map those concepts to tables and columns afterward, see Publish bindings through the API.

Before you begin

Before you start, make sure you have:

Ontology extension: An administrator has installed the Ontology extension in your account. Until then, these routes and MCP tools are not available.
Credentials: ATLAN_GATEWAY_URL and ATLAN_TOKEN in your environment, from an approved secret store. See Send bearer token.
Workspace: A disposable workspace you can write to while you evaluate the contract.
jq: The examples use it to keep artifact IDs, exact version ordinals, and content hashes from each response. Those three values identify the precise draft version that publication consumes.

The Ontology API stores definitions and directly managed governed knowledge records. It does not copy warehouse or customer data into Atlan Trident, map tables, generate SQL, or execute actions, and action definitions are contracts that are never run. The steps follow this lifecycle:

ontology → logical drafts → validation → release → bounded agent context

Create ontology

An ontology is the governance root for its logical resources. Create it in Ontology Studio, the client for the Ontology extension. In the Atlan app, Ontology’s list and creating open in Brain under Ontologies. To open the studio in a browser instead, go to https://api.atlan.com/ontology/v1/ui/, complete the Gateway sign-in, and choose a workspace. Then:

Choose New ontology, then Start blank. With no ontology yet, the page shows the same three options instead: Start blank, Import a file, and Draft with an agent. Choose Start blank.
Select the Workspace, enter a Name, and set the API name to example_ontology.
Optionally open More options and choose an Icon and colour. They show wherever the ontology is listed; leave either on Default to use the standard tile.
Under More options, keep Backward compatible as the Versioning policy, then choose Create ontology. Under this policy a breaking change needs a new major version.

Studio opens the new ontology, and the page address ends in #/o/<ontology_id>. Copy that ID into your shell:

export ONTOLOGY_ID="ontology_01example"

The icon and colour are presentation only: they are not part of a release snapshot, and you can change them in the ontology’s Settings before or after publishing.The home page’s All ontologies list can be searched by name, API name, or description, filtered by release status (All, Published, Not published), and sorted by name, latest release, or last edit. Its last-edited time counts edits to the ontology’s definitions, not only the ontology itself.Studio can also author resources in Form and JSON views, show the catalog as a graph (see Manage ontology in Studio), and build derived properties and links in its Builder and Explain views. Its Import view accepts native JSON, RDF/RDFS, OWL, and SKOS documents and saves at most 100 resources as drafts in one transaction. After you review the preview, select I approve creating these definitions as drafts in the selected ontology. Nothing will be published., then choose Save approved drafts. If Studio reports Save outcome unknown, check the ontology’s definitions before you import again: a failed response does not prove the save failed, and the same preview cannot be submitted twice. The rest of this recipe uses the API.

Import logical resources

Describe a Customer object, a SupportCase object, and a typed link between them as a native JSON document. Property value schemas stay inside their owning object because they share its lifecycle. Each artifact_id is a placeholder: on apply, the link’s source and target references are rewritten to the drafts created in the same transaction.

LOGICAL_MODEL=$(jq -n \
  --arg ontology_id "${ONTOLOGY_ID}" \
  '{
    canonicalization_version: 1,
    ontology_id: $ontology_id,
    resources: [
      {
        kind: "ontology_object_type",
        artifact_id: "ontology_object_type_01customer",
        api_name: "customer",
        definition: {
          ontology_id: $ontology_id,
          api_name: "customer",
          object_kind: "entity",
          implements: [],
          properties: [
            {
              api_name: "customer_id",
              is_required: true,
              is_identifier: true,
              value_schema: {kind: "string", max_length: 128}
            },
            {
              api_name: "status",
              is_required: true,
              value_schema: {
                kind: "string",
                enum: ["prospect", "active", "inactive", "churned"]
              }
            }
          ]
        }
      },
      {
        kind: "ontology_object_type",
        artifact_id: "ontology_object_type_01supportcase",
        api_name: "support_case",
        definition: {
          ontology_id: $ontology_id,
          api_name: "support_case",
          object_kind: "entity",
          implements: [],
          properties: [
            {
              api_name: "case_id",
              is_required: true,
              is_identifier: true,
              value_schema: {kind: "string", max_length: 128}
            }
          ]
        }
      },
      {
        kind: "ontology_link_type",
        artifact_id: "ontology_link_type_01customerhascase",
        api_name: "customer_has_support_case",
        definition: {
          ontology_id: $ontology_id,
          api_name: "customer_has_support_case",
          source: {
            kind: "ontology_object_type",
            artifact_id: "ontology_object_type_01customer"
          },
          target: {
            kind: "ontology_object_type",
            artifact_id: "ontology_object_type_01supportcase"
          },
          source_cardinality: "one",
          target_cardinality: "many",
          inverse_api_name: "support_case_belongs_to_customer",
          properties: []
        }
      }
    ]
  }')

The link type is a logical definition, not only a Registry relationship. It has its own stable identity, endpoint types, two-sided cardinality, inverse name, version history, and optional properties.Preview the document. A preview validates the proposal and never changes the ontology:

IMPORT_REQUEST=$(jq -n \
  --arg ontology_id "${ONTOLOGY_ID}" \
  --arg document "${LOGICAL_MODEL}" \
  '{
    ontology_id: $ontology_id,
    document: $document,
    format: "native_json",
    serialization: "json",
    adapter_version: "native-json/1"
  }')

MODEL_PREVIEW=$(curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/ontology/v1/imports/preview" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "${IMPORT_REQUEST}")

jq '{preview_id, is_valid, validation_diagnostics, apply_supported}' <<<"${MODEL_PREVIEW}"

When is_valid and apply_supported are both true, apply the unchanged request with the returned preview_id:

MODEL_APPLY=$(curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/ontology/v1/imports/apply" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "$(jq \
    --arg preview_id "$(jq -r '.preview_id' <<<"${MODEL_PREVIEW}")" \
    '. + {preview_id: $preview_id}' <<<"${IMPORT_REQUEST}")")

jq '[.artifacts[] | {kind, id, version_ordinal}]' <<<"${MODEL_APPLY}"

Apply recomputes the preview, refuses a request whose document or options changed since the preview, and creates every proposed resource in one Registry transaction, or none of them. It creates drafts; it does not publish a release. A document above 100 resources, or one resource that needs too many reference rewrites, stays previewable but cannot be applied in one request. A document can be at most 8 MiB, and an RDF, OWL, or SKOS import also needs profile and base_iri; see Import preview returns 422. If the preview is not valid, see Import preview has is_valid: false.

Validate and publish release

Pin the exact drafts to publish. The apply response’s artifacts are the created drafts, each with its ID, version ordinal, and content hash. Publication never resolves latest separately for each resource, so if a pinned draft changes before you publish, the request fails instead of publishing a different model.

SOURCE_VERSIONS=$(jq '[.artifacts[] | {
  kind,
  artifact_id: .id,
  version_ordinal,
  content_hash: .content_hash_hex
}]' <<<"${MODEL_APPLY}")

Keep this manifest with the change under review. Validate the complete graph before assigning a release number:

VALIDATION=$(curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/ontology/v1/validations" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "$(jq -n \
    --arg ontology_id "${ONTOLOGY_ID}" \
    --argjson source_versions "${SOURCE_VERSIONS}" \
    '{ontology_id: $ontology_id, source_versions: $source_versions}')")

jq '{is_valid, diagnostics, resource_count}' <<<"${VALIDATION}"

Publish only when is_valid is true. If publication rejects a draft that validated, see Publish rejects pinned draft.

RELEASE=$(curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/ontology/v1/releases" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "$(jq -n \
    --arg ontology_id "${ONTOLOGY_ID}" \
    --argjson source_versions "${SOURCE_VERSIONS}" \
    '{
      ontology_id: $ontology_id,
      release: "1.0.0",
      source_versions: $source_versions
    }')")

RELEASE_ID=$(jq -r '.id' <<<"${RELEASE}")
jq '{id, release, manifest_digest, compatibility}' <<<"${RELEASE}"

Publication appends the canonical graph to the stable ontology artifact, then releases that exact version through Core Registry. The release ID has the rel_... form, and reading it later does not depend on draft heads.

ontology_release is not an artifact kind. Publish through POST /ontology/v1/releases so Ontology validates the graph and creates the immutable snapshot before Core Registry cuts the release.

Retrieve bounded agent context

An agent usually needs a relevant subgraph, not the whole release. Query one exact release with explicit resource, traversal-depth, and token bounds:

CONTEXT=$(curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/ontology/v1/context-queries" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "$(jq -n \
    --arg ontology_id "${ONTOLOGY_ID}" \
    --arg release_id "${RELEASE_ID}" \
    '{
      ontology_id: $ontology_id,
      release_id: $release_id,
      query: "customer support cases",
      include: ["object_types", "link_types"],
      max_resources: 4,
      max_depth: 2,
      max_tokens: 4000,
      diagnostics: true
    }')")

jq '{
  release_id,
  manifest_digest,
  resources,
  token_estimate,
  truncated,
  refinement_hints,
  diagnostics
}' <<<"${CONTEXT}"

Each returned resource includes selected_because and depth. Check truncated and refinement_hints before treating the response as enough for the task. The service filters search candidates to the selected release and expands typed dependencies without mixing in newer drafts.An MCP client reaches the same operation as extension__ontology__get_context:

{
  "ontology_id": "ontology_01example",
  "release_id": "rel_01example",
  "query": "customer support cases",
  "include": ["object_types", "link_types"],
  "max_resources": 4,
  "max_depth": 2,
  "max_tokens": 4000,
  "diagnostics": true
}

For the full input contract and limits, see Get bounded ontology context.To ask a structural question instead, compile a bounded, read-only SPARQL SELECT query against the same release:

QUERY_PLAN=$(curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/ontology/v1/query-plans" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "$(jq -n \
    --arg ontology_id "${ONTOLOGY_ID}" \
    --arg release_id "${RELEASE_ID}" \
    --arg query 'SELECT ?type WHERE { ?type a <http://www.w3.org/2002/07/owl#Class> . } LIMIT 25' \
    '{
      ontology_id: $ontology_id,
      release_id: $release_id,
      query: $query,
      max_operations: 128,
      include_definitions: false
    }')")

jq '{
  release_id,
  manifest_digest,
  query_mode,
  is_executable,
  requires_bindings,
  logical_plan,
  resolved_resources,
  unresolved_terms,
  result_bindings,
  diagnostics
}' <<<"${QUERY_PLAN}"

The planner resolves ontology identifiers and returns logical operations. A bounded basic-graph-pattern subset can also return bindings from ontology metadata. Queries over business records stay planning-only and set requires_bindings: true: this operation does not read instances, resolve physical bindings, or emit SQL. An MCP client runs it with extension__ontology__get_query_plan.To look up governed records such as policies and controls in Studio, open the Agent context page, choose the Ask tab, choose Knowledge records, and pick a release. Enter keywords in Record search terms, or leave it empty to list the applicable records. Set Valid as of to the business time you care about, then choose Ask. Studio returns records as evidence, not a generated answer: only records pinned to the selected release, at their current versions rather than a frozen record-set snapshot, 20 at a time. Each record card lists its governed fields, typed relationships, and supporting documents.Studio reads Knowledge records through MCP and has no REST fallback. If the MCP surface is not enabled on your deployment, or the Ontology tools are not installed, Studio shows an error instead of records.

Verify release

Read the published schema back by its release ID:

curl -sS --fail-with-body \
  "${ATLAN_GATEWAY_URL}/ontology/v1/ontologies/${ONTOLOGY_ID}/releases/${RELEASE_ID}/schema" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" | \
  jq '{release_id, release, manifest_digest, resources: (.schema.resources | length)}'

Before handing the release to an agent or another service, confirm that:

The validation response had is_valid: true and no error diagnostics.
The published manifest_digest matches schema reads and context responses.
Context retrieval names the intended release_id and stays within its bounds.
truncated is false, or the caller follows the returned refinement hints.

To see release history, list canonical snapshots through Ontology:

curl -sS --fail-with-body \
  "${ATLAN_GATEWAY_URL}/ontology/v1/ontologies/${ONTOLOGY_ID}/releases?limit=50&offset=0" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" | jq

Core Registry holds the generic lifecycle and channel pointers:

curl -sS --fail-with-body \
  "${ATLAN_GATEWAY_URL}/registry/v1/artifacts/ontology/${ONTOLOGY_ID}/releases" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" | jq

curl -sS --fail-with-body \
  "${ATLAN_GATEWAY_URL}/registry/v1/artifacts/ontology/${ONTOLOGY_ID}/releases/latest" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" | jq

Superseded releases stay readable by exact ID. A withdrawn release stays in history but is no longer a selectable distribution target.

Export release (optional)

To hand the model to an RDF or OWL tool, list the available adapter versions, then export the release through the documented OWL subset:

curl -sS --fail-with-body \
  "${ATLAN_GATEWAY_URL}/ontology/v1/adapters" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" | jq

OWL_EXPORT=$(curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/ontology/v1/exports" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "$(jq -n \
    --arg ontology_id "${ONTOLOGY_ID}" \
    --arg release_id "${RELEASE_ID}" \
    '{
      ontology_id: $ontology_id,
      release_id: $release_id,
      format: "owl",
      serialization: "turtle",
      adapter_version: "owl/1",
      profile: "owl2-dl-supported-subset",
      base_iri: "https://example.test/ontology/logical-model#"
    }')")

jq '{adapter_version, media_type, document_digest, report}' <<<"${OWL_EXPORT}"

The document field contains Turtle. The report states every approximation, omission, or unsupported construct, so confirm the consumer accepts that profile and loss report. OWL and RDF are interchange formats over the native model; they do not change Registry storage or validation.Importing an OWL or RDF document works like the native import: preview it, then apply the unchanged request with its preview_id. A preview never changes the ontology, and adapters never fetch remote imports.

IMPORT_PREVIEW_REQUEST=$(jq -n \
  --arg ontology_id "${ONTOLOGY_ID}" \
  --arg document "$(jq -r '.document' <<<"${OWL_EXPORT}")" \
  '{
    ontology_id: $ontology_id,
    document: $document,
    format: "owl",
    serialization: "turtle",
    adapter_version: "owl/1",
    profile: "owl2-dl-supported-subset",
    base_iri: "https://example.test/ontology/logical-model#"
  }')

IMPORT_PREVIEW=$(curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/ontology/v1/imports/preview" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "${IMPORT_PREVIEW_REQUEST}")

jq '{preview_id, apply_supported, proposed_resources, report}' <<<"${IMPORT_PREVIEW}"

This example previews the export of drafts you already imported. Apply derives each draft’s Registry name from its api_name and ontology, so applying it to the same ontology fails with a uniqueness conflict. To copy the model instead, set ontology_id to a different ontology, in this workspace or another one you can write to; the document needs no edits. Apply creates new drafts with fresh IDs, rewrites the references between them, and keeps each resource’s canonical IRI, name, and description. For RDF and OWL, use the same adapter options as the export. Bindings, record sets, and releases are not copied. An MCP client can run Export ontology release and Preview ontology import.

Manage ontology in Studio

Ontology Studio also manages ontologies after you publish:

Ontology list: Search All ontologies by name, API name, or description, filter by release status (All, Published, Not published), and sort by name, latest release, or last edit. The last-edited time counts edits to the ontology’s definitions, not only the ontology itself.
Graph: The Graph page draws object types as cards and links as lines, each labelled with its verb, with line ends that show cardinality. A large model opens on Domains: groups of closely linked types, found from the links and named after their two best-connected types. Open a domain to see its types, or choose All domains to go back. Types shows the type cards, and Focus shows one type with its sources on the left and its targets on the right. When an ontology has both model definitions and terminology, choose Model, Terminology, or Model + terms to set what the graph shows; it opens on Model. To focus a resource, search Find a type, link or property and pick a result.
Release page: Each published release has its own page. Ask this release and Query this release open the context and query views for that exact release, the Export tab exports it, and Built on this release shows the binding families pinned to it and the record set it governs.
Settings: Rename the ontology or change its description at any time. Its namespace and versioning policy are fixed once a release exists, so every release reads under the same rules. Archive ontology hides the ontology from lists for everyone in the workspace and keeps its definitions and release history. Archiving takes admin permission on the workspace: if your role lets you create and edit the ontology but not archive it, the Archive button is unavailable and Studio explains who can archive it for you. Studio asks you to type the ontology’s API name to confirm.
Unsaved changes: While you edit a resource, a bar stays in view and shows how many changes are unsaved. If the draft cannot save yet, the bar names what to fix: a field with an error, or JSON edits to apply or discard first. Choose Save draft, press ⌘S or Ctrl+S, or choose Discard.
Diagnostics: A validation diagnostic that names a property links to it in the resource it belongs to.

Troubleshooting

If an import or validation is not valid, apply is refused or conflicts, publication rejects a pinned draft, or context comes back truncated, see Ontology errors.

Next steps

Publish bindings through the API: Bind this release to tables, columns, and governed joins.

Register and manage agents

Give agents business context

Observe agent runs

Evaluate and improve agents

Track agent cost

Publish ontology through API

Before you begin

Manage ontology in Studio

Troubleshooting

Next steps

See also