Skip to content

Tutorial

API quickstart

API quickstart

2 min

This walkthrough uses an operation from the published catalogue. Verify an API key, workspace and accessible records without writing to the model.

Prerequisites

  • An accessible workspace and an API key authorized to read instances.
  • A Client type created using the UI quickstart.
  • The workspace identifier and Client type UUID, obtained from the application.
  • curl and optionally jq for readable output.

Create a key with the necessary permissions in API keys. Copy it when created and store it in your secret manager. A script's API key is separate from your browser session.

1. Set the parameters

export ONTOLOGIE_API_URL="https://api.ontologie-growthsystemes.com"
export ONTOLOGIE_API_KEY="df_REPLACE_WITH_YOUR_KEY"
export WORKSPACE_ID="WORKSPACE_UUID"
export CLIENT_TYPE_ID="CLIENT_TYPE_UUID"

Replace the three placeholders. This is the production API URL; use your environment's URL when working elsewhere. Do not share the real key.

2. Read a page of instances

curl --fail-with-body --silent --show-error   "$ONTOLOGIE_API_URL/api/v1/object-types/$CLIENT_TYPE_ID/instances"   -H "X-API-Key: $ONTOLOGIE_API_KEY"   -H "x-workspace-id: $WORKSPACE_ID" | jq .

HTTP paths start with /api/. /docs/reference/api/ is a documentation path, not an API endpoint.

A successful response contains the instances authorized for the requested type and context. An empty list can be valid. API Manager documents this operation's parameters and pagination; a single page does not prove that you have read every customer.

3. Compare with the interface

  1. Open Client and Instances in the same workspace.
  2. Find instance CLI-001 from the UI quickstart.
  3. Compare its identifier and name with the response.
  4. If missing, check the type, key scope and filters; see Diagnose missing data.

API Manager's test panel uses your user session. Success there does not establish that an external key has equivalent permissions.

Common errors

CodeCheck
401Key is present, valid and not revoked
403Reading permissions and workspace access
404Environment URL, type UUID and published route
429Request limits and retry delay

Keep the method, path, HTTP code and request identifier for diagnosis. Remove the key from shared screenshots and logs.

Expected result and next step

You have read data using an API key and compared it with a record in the interface. No data cleanup is required.

Before writing, confirm that the exact method and path appear in the published catalogue and consult their schema. A create button in the interface does not automatically publish its route for external integrations. See API reference and Prepare a controlled action.

Did this page help you achieve your goal?