Explore the API and OpenAPI reference

The interactive reference shows API operations, parameters and response formats. You can read it without a key; executing an authenticated operation uses the key you supply.

Find and execute an operation

1. Open Organization settings > API > Interactive documentation, or visit /api-doc on your Boldo environment.
2. Search for an operation and narrow the list by category, HTTP method or user type.
3. Click Authenticate, enter the target organization's API key, then Authenticate again.
4. Open a read operation first, such as the asset-type list.
5. Check the path, parameters, expected response and generated example. Replace illustrative values with actual identifiers or keys.
6. Click Execute and inspect the displayed response.
7. For a write, read back the modified object before continuing with additional operations.

Use Change API key to switch the execution credential. Signing into the Boldo interface does not replace this authentication step.

Execute sends a real request

For a compatible operation, enter its scenario query parameter to target that scenario. Leaving it empty targets real data. The reference is not a simulation. Write operations create, change or archive data using the supplied key. Review the organization, scenario and complete request before clicking Execute.

The optional AI request assistant uses your web session's AI access and organization. API execution uses the supplied key. Check that these contexts correspond before using a proposed request. A generated example is not proof that its asset type exists in the key's organization.

Choose an OpenAPI schema

Boldo provides OpenAPI 3.1 schemas in JSON and YAML. Use your environment's origin with these paths:

Schema	Paths	Access
Generic	/api/v1/openapi/base.json and /api/v1/openapi/base.yaml	Public; describes the general API contract.
Typed	/api/v1/openapi/typed.json and /api/v1/openapi/typed.yaml	API key with at least Viewer access and an API-enabled plan.

The interactive reference requires authentication for its Execute button even when showing a public schema operation. The generic schema URLs themselves remain accessible without a key.

The typed schema describes your organization's metamodel, for asset types and relationship types alike: property types, enum values, constraints and calculated properties marked read-only. Hidden properties are excluded. Regenerate it after metamodel changes before relying on old generated clients or validation.

Schema validity does not grant permissions on every asset or access domain. Business rules and the key's effective permissions are checked when requests run. Use key management to diagnose those permissions.

When importing a schema into another tool, verify its server address. In particular, a localhost example in the schema is not necessarily your local environment's port. Use the origin where your intended Boldo instance actually runs.

Explore analysis operations

POST /analytics/assets/aggregate computes grouped measures. POST /analytics/assets/impact follows configured relationship paths. Both are read operations, require at least Viewer access and apply business permissions. Their compatible scenario context uses the scenario query parameter.

Both operations validate filters on asset properties and system attributes. Unknown asset-type or property keys and values incompatible with their operators return HTTP 400. See filter validation.

For example, this impact request follows one outgoing relationship type for up to three hops:

{
  "sources": ["application:reference:APP-DEMO-001"],
  "stages": [{
    "relationships": [{
      "relationship_type_key": "depends_on",
      "direction": "outgoing"
    }],
    "max_depth": 3
  }],
  "include": ["paths"],
  "page": { "number": 1, "size": 50 }
}

Replace the composite source ID and relationship key with values from your organization. Traversal definitions belong inside stages, not a root-level relationships property.

The impact API accepts at most 100 explicit sources, five stages and 200 traversal definitions across stages. The server traversal limit is 30 hops; page size is at most 100. Dynamic sources use source_asset_type_key and source_filter.

target_filter cuts non-matching branches. stop_conditions includes the reached node but stops further traversal. display_filter only hides results without preventing traversal; hidden intermediate nodes can appear in hidden_path_assets.

Pagination applies to impacted assets. Sources, relationships and summary describe the analysis as a whole. Read truncation and depth-limit indicators before presenting paths as exhaustive. See impact analysis for the user-facing meaning of stages and filters.

Keep the integration aligned

Use the reference served by the environment you call. Refresh typed definitions after metamodel changes and inspect actual responses during integration updates. Keep parameter names, enum keys and operation-specific formats from the reference rather than translating them into interface labels.

When upgrading an existing integration, check the metamodel response shape. GET /metamodel returns separate asset_types and relationship_types collections. Asset types no longer contain a nested relationships collection, and the response no longer includes roles. Read each relationship type's properties from its own definition. These response changes do not remove permission checks from API operations.

List choices in the metamodel response include a nullable description containing their help text. Relationship source_marker and target_marker styles also include open_diamond, open_triangle and open_arrow. These describe appearance; they do not impose relationship cardinality. Update integrations that validate these fields against a fixed set of values.

For request construction, pagination and recovery, continue with reading and synchronization or writing data.