API

Boldo exposes a complete REST API at /api/v1/. Use it to integrate Boldo with external systems, automate recurring tasks, or build custom tooling on top of your knowledge base.

Required plan

API access depends on your plan. Go to Organization → Developer to verify your access.

Create an API key

1. Open Organization → Developer.
2. Click "Create API Key".
3. Enter a name and an optional description.
4. Choose a permission type: Viewer, Editor, or Admin.
5. Assign one or more roles to scope the key's access.
6. Click "Create".
7. Copy the secret immediately. It is displayed only once.

Each editor, administrator, or owner can create multiple API keys. Every key has its own name, permission level, and role assignments.

Security

Store the secret in a secure vault or environment variable. Never commit it to source control. If you suspect a key was exposed, delete it and create a new one.

Manage API keys

Go to Organization → Developer to see the API keys you are allowed to manage.

• Editors see only their own keys.
• Administrators and owners can see and manage all keys in the organization.

From this screen you can update a key's name, description, permission type, or roles. Administrators and owners can also transfer a key to another user. You can delete keys you no longer need.

API capabilities

The V1 API covers the main resources you work with in the Boldo interface.

• Assets -- Create, read, update, and delete assets. Address an asset by its Boldo ID (the UUID assigned on creation), or, when the asset type has a unique-key property defined in the metamodel, by a composite key in the form {asset_type_key}:{unique_property_key}:{value}.
• Relationships -- Create, read, and delete relationships between assets.
• Bulk operations -- Create up to 10,000 assets or 10,000 relationships in a single request. Update up to 10,000 assets in a single request.
• Search -- Query assets and relationships with nested filters and logical groups across any property.
• Analytics -- Run aggregation queries with measures (count, count_distinct, sum, average) and group or break down results by properties, system attributes, or related asset types.
• Metamodel -- Read asset types, property definitions, and relationship types.
• Administration -- Manage API keys (create, read, update, delete). Read roles, access domains, and users.

Query patterns

The V1 API offers two ways to query assets and relationships, depending on how complex the query is.

List endpoints

GET /assets and GET /relationships return paginated lists with equality filtering only. Pass conditions as query-string parameters, for example filter[asset_type_key]=server or filter[properties.status]=active. Use these when a handful of equality conditions is enough.

Pagination uses page[number] (default 1) and page[size] (default 50, maximum 100). Sort with sort=field or sort=-field for descending order.

Search endpoints

POST /search/assets and POST /search/relationships accept a JSON body with operator-based conditions and nested AND/OR groups. Use these when the list endpoints are too restrictive.

The following operators are available:

• equals, not_equals
• greater_than, greater_than_or_equals, less_than, less_than_or_equals
• contains, not_contains, starts_with
• includes, not_includes (membership in a multi-select value)
• in, not_in (match against an array of values)
• is_empty, is_not_empty

Expanding related data

Both list and search endpoints accept include to pull related data into the response in a single round-trip:

• include=relationships -- attach the asset's relationships with IDs only
• include=relationships,relationships.related_asset -- also expand the related asset on each relationship
• include=relationships,relationships.related_asset.properties -- also include the related asset's property values

On the relationships endpoints, use include=source_asset or include=target_asset to expand either end of a relationship, and append .properties to pull in their property values.

Included relationships can be paginated, filtered, and sorted independently. On list endpoints, use relationships_page, relationships_filter, and relationships_sort. On the search endpoints, pass a relationships block inside the request body with the same page, filter, and sort shape as the top-level query.

Bulk operations

POST /bulk/assets, PATCH /bulk/assets, and POST /bulk/relationships accept up to 10,000 items per request.

Bulk requests are all-or-nothing. If any item fails validation, the whole request is rejected and nothing is written. This keeps the inventory consistent when a batch is partially wrong.

Each item can carry an optional client_ref string. The value is echoed back in the response alongside the created or updated ID, so you can map Boldo IDs back to your source records without a second lookup. This is especially useful for idempotent imports.

Scoped sync for embedded relationships

When you create or update an asset with embedded relationships, each pair of (direction, relationship type) is replaced wholesale. Sending related_assets: [] for a given direction and type clears every existing relationship of that type on that asset.

This matters most on patch operations: omit a direction/type pair if you do not want its relationships touched, and include it only when you intend to fully replace the set. To add or remove a single relationship without touching the rest, use the dedicated /relationships or /bulk/relationships endpoints instead.

Date formats

created_at and updated_at are timestamps: they record when a change happened, down to the second, in ISO 8601 UTC (YYYY-MM-DDTHH:mm:ssZ).

Date properties defined in the metamodel describe a day rather than a moment -- a go-live, a contract start, a review date -- so they use YYYY-MM-DD. The API rejects full timestamps on those fields.

OpenAPI specification

The Boldo API follows the OpenAPI standard. OpenAPI is a widely adopted format that describes REST APIs in a machine-readable way -- endpoints, parameters, request bodies, and response schemas are all defined in a single file.

This means you can use the spec with any tool that understands OpenAPI. For example:

• Postman or Insomnia -- import the spec to get a ready-made collection of all endpoints
• Code generators -- generate a typed API client in your language of choice (TypeScript, Python, Go, etc.)
• CI pipelines -- validate payloads against the spec before sending them
• AI assistants -- feed the spec to an LLM to help write integration scripts

Interactive documentation

Boldo also generates an interactive API documentation page directly from the spec. The page groups all V1 endpoints by resource (Assets, Relationships, Bulk, Search, Analytics, etc.) so you can browse, authenticate, and test requests without leaving the browser.

Base spec vs Typed spec

Two specifications are available, each in JSON and YAML:

• Base spec at /api/v1/openapi/base.json (or .yaml) -- describes all endpoints with generic schemas. It does not require authentication and works for any organization. Use it to discover the API, set up a client, or import into Postman.
• Typed spec at /api/v1/openapi/typed.json (or .yaml) -- requires authentication. It includes schemas that reflect your actual metamodel: asset types, property names, enum values, and relationship types are all part of the spec. Use it when you want request and response schemas that match your specific knowledge base, for example to generate a fully typed client.

Authentication and permissions

Authenticate every request by sending your API key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

The key inherits the permission type and roles you assigned at creation. A key with the Viewer permission can only read data. An Editor key can read and write. An Admin key has full access.

You can delegate access safely by creating a key scoped to a narrow set of roles. This limits what the key can see and modify, even if the permission type is broad.

Administrators can also delegate a key to another user, which is useful when a user who owns a production key leaves the organization. The effective permission type is always the minimum between the key's type and the owning user's type. For example, an admin key transferred to an editor will behave as an editor key. An editor can only assign roles they already have.

Rate limiting

API requests are rate-limited per organization, and the quota is shared across every API key the organization has issued. If you receive a 429 response with rate_limit_exceeded, wait before retrying.

When to use the API

Use the API when you need repeatable or programmatic work on the knowledge base. Typical cases include integrating Boldo with another system, running recurring synchronization jobs, automating repeated updates, and building scripts or internal tools.

Use Import a CSV file instead when the need is a one-time bulk import handled by business users.

Use the UI when you are updating a few assets manually, adjusting the metamodel, or exporting a one-time CSV or image.