> ## Documentation Index > Fetch the complete documentation index at: https://docs.synq.io/llms.txt > Use this file to discover all available pages before exploring further. # RenderOsi > Render a semantic model as an OSI document. The document is always YAML. The document is always valid OSI. When the model has no value for a property that OSI requires, the document has a fallback value: a field with no expression gets its own name as the expression, and a group with no source gets its name as the source. What OSI has no property for is kept in a custom extension with the vendor name COALESCE, so ParseOsi gives back the same model. Give the whole model. A model read with field_names or without the definitions renders each measure as a plain column. To get the OSI document of an entity, call SemanticModelsService.BatchGetSemanticModels with SEMANTIC_MODEL_FORMAT_OSI. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/entities/semantic-models/v1alpha/osi/render openapi: 3.1.0 info: version: '1.0' title: SYNQ servers: - url: https://developer.synq.io - url: https://api.us.synq.io - url: https://api.au.synq.io security: - bearerAuth: [] tags: - name: synq.agent.recon.v1.SuiteDeploymentService description: |- SuiteDeploymentService is the platform plane of reconciliation. SuiteConfigService is the developer/authoring sandbox (edit, version, run ad-hoc with your own credentials — preview-only, no Entity, no Run, no Issue). A deployment is what Coalesce Quality actually runs on the workspace's behalf: a frozen snapshot of a suite config, mapped to workspace-level Coalesce Quality integrations, optionally scheduled or triggerable by API. Identity: every deployment has a stable deployment_id (UUIDv7) assigned on first promote. It survives re-promotes, schedule/mapping changes, and pause/resume. Downstream AssetCommand / RunCommand publication keys off deployment_id so Entity identity does not fragment on promote churn. - name: synq.agent.recon.v1.YamlService description: >- YamlService provides stateless conversion between YAML config format and proto. This is useful for UI editors that need to display/edit suite configs as YAML. - name: synq.agent.sre.v1.FeatureRequestService description: >- FeatureRequestService allows MCP clients to submit feature requests when users encounter missing capabilities. This is a last-resort service — it should only be used when no existing tool can fulfill the user's request. - name: synq.agent.sre.v1.LlmService description: Service for evaluating LLM requests and producing structured output. - name: synq.agent.sre.v1.TriageService description: >- Service for managing issue triage operations, allowing LLM agents to conclude investigations and record evidence during the triage process. - name: synq.alerts.services.v1.AlertsService description: |- AlertsService provides operations for managing alert configurations. Deprecated: use synq.alerts.services.v2.AlertsService. The v2 service selects entities with the canonical synq.queries.v1.Query + resolver_ql trigger; this v1 service, which uses the bespoke EntityGroupQuery selection, is scheduled for removal. Migrate existing integrations to v2. - name: synq.alerts.services.v2.AlertsService description: |- AlertsService provides operations for managing alert configurations. It supersedes synq.alerts.services.v1.AlertsService: entities are selected with the canonical synq.queries.v1.Query + resolver_ql trigger rather than the bespoke EntityGroupQuery. - name: synq.auth.iam.v1.IamService - name: synq.entities.executions.v2.EntityExecutionsService description: >- EntityExecutionsService provides read-only access to entity execution history. This service allows customers to retrieve information about all executions that happened on their entities, including execution status, timing, and messages. Use cases: - Retrieve execution history for specific entities - Filter executions by time range, status, or execution type - Get aggregated summaries of execution activity - Track execution trends and patterns - name: synq.datachecks.sqltests.v1.SqlTestsService description: SqlTestsService is a service for managing SqlTests. - name: synq.datachecks.sqltests.v1.SqlTestsDeploymentRulesService description: |- SqlTestsDeploymentRulesService manages SqlTestDeploymentRules — rules that dynamically deploy SQL test templates onto every table or view a query matches, resyncing over time as the match set changes. - name: synq.datachecks.testsuggestions.v1.TestSuggestionsService - name: synq.datachecks.v1.TriggerService description: TriggerService provides synchronous execution of datachecks on entities. - name: synq.dataproducts.v1.DataproductsService description: DataproductsService can be used to manage data products. - name: synq.dataproducts.v2.DataproductsService description: |- DataproductsService manages data products — named, owned groupings of data assets with a membership definition, a priority and an optional folder. Ids are opaque UUIDs supplied by the caller, which makes writes idempotent (a retried create converges instead of duplicating). Mutable fields are optional on Upsert: a field that is set is written, a field that is omitted is left unchanged. Pass the `etag` you last read to guard against overwriting a concurrent edit. A data product is a leaf in the reference graph — its definition may not reference another data product or domain — so membership resolution always terminates. - name: synq.deliveries.v1.DeliveriesService description: >- DeliveriesService reports what was sent to your notification integrations — webhooks, PagerDuty, Opsgenie — and what came back. It answers the three questions an integration owner has. "Did this event reach my endpoint": list the deliveries for an event id and read the outcome of each. "Why did my endpoint reject it": read the attempts, which carry the request as it was sent and the response as it came back. "Why did I get nothing at all": every delivery that sent nothing records a reason, so a silent integration can be explained rather than guessed at. Deliveries are kept for 90 days. Credential-bearing header values are never returned, on either side of an attempt — see `Header`. - name: synq.domains.members.v1.DomainMembersService description: DomainMembersService can be used to manage domain memberships. - name: synq.domains.v1.DomainsService description: DomainsService can be used to manage domains. - name: synq.domains.v2.DomainsService description: >- DomainsService manages data domains — named areas of ownership that group the assets, data products and sub-domains belonging to one part of the business. Ids are opaque UUIDs supplied by the caller, which makes writes idempotent (a retried create converges instead of duplicating). Mutable fields are optional on Upsert: a field that is set is written, a field that is omitted is left unchanged. Pass the `etag` you last read to guard against overwriting a concurrent edit. A domain may contain other domains and data products, so membership resolution is recursive. Every write that adds such a reference — including a change of `parent_id` — is rejected if it would close a loop, so a definition can always be resolved in finite time. - name: synq.entities.activity.v1alpha.ActivityService description: >- ActivityService reads the query history of a workspace's data platforms: how popular an entity is, who reads and writes it, what one login, tool, job or person touched and what it cost, and where a workspace's compute goes. Every read covers a window of whole UTC hours, by default the 30 days before the current hour. A login's reads count toward popularity as its service account's popularity policy says (see synq.entities.platformusers.v1alpha.ServiceAccountsService), and Coalesce Quality's own queries never count. Weights are per query, in each platform's own figures. bytes_scanned is never a cost, and no platform reports cost per table, so an entity's share of a query is an equal split. Nothing here is credits or currency. - name: synq.entities.annotations.v1.AnnotationsService description: >- AnnotationsService provides operations for managing and querying entity annotations. Annotations are key-value pairs that can be attached to entities for categorization and filtering. - name: synq.entities.changes.v1.ChangesService description: >- ChangesService provides functionality to track and retrieve all types of changes to data entities. This unified service returns ALL change types for an entity: - Git commits: Changes to code files (dbt models, SQL files) tracked in version control - Schema changes: Database schema modifications (columns added/removed/changed) - SQL definition changes: View/materialized view definition updates detected by Coalesce Quality Changes are returned with structured metadata including: - For git commits: structured statistics (directories, file types, top changes) - For schema changes: detailed column-level diffs - For SQL changes: before/after SQL definitions Use cases: - "What changed in the last week for table X?" → Returns git commits, schema changes, SQL changes - "Show me all commits affecting this dbt model" → Returns git commits with lineage context - "What schema changes happened to this table?" → Returns schema changes detected by Coalesce Quality - name: synq.entities.checks.v1.ChecksCategoriesService description: |- ChecksCategoriesService lets workspace admins set explicit category overrides on individual checks. An explicit category is the authoritative category for a check — it takes precedence over the categories computed by the workspace's categorisation rules. It is a public API so customers can manage check categories programmatically; the same service is also mounted on the internal API. The workspace and the acting identity are always taken from the request context, never from the payload. - name: synq.entities.checks.v2.ChecksCategoriesService description: |- ChecksCategoriesService reads and edits the categories of the checks in a workspace. Categorising checks is what turns a long list of tests into a picture of data quality: it lets you ask how much of a data product is covered for completeness, or which freshness checks exist across three warehouses that each name the same idea differently. Every check resolves to at most one category per dimension: * technical — what kind of check this is, mechanically ("nullness", "uniqueness", "freshness"); * governance — what the check is for, in data-quality terms ("Completeness", "Accuracy", "Timeliness"). The two are independent, and each resolves from three sources, in descending precedence: a category set explicitly on the check through this service, a category the producing tool declared, and a category one of the workspace's categorisation rules computed. Rules are managed by ChecksCategorisationRulesService and are the right tool for anything that generalises; set a category explicitly only for the checks that are genuine exceptions. The workspace and the acting identity always come from the request credentials, never from the payload. - name: synq.entities.checks.v2.ChecksCategorisationRulesService description: |- ChecksCategorisationRulesService manages the rules that categorise a workspace's checks automatically. A rule says "checks matching this predicate get this category on this dimension". Rules are the scalable way to categorise: they apply to checks that already exist and to every check ingested afterwards, so a new dbt package or a new warehouse does not mean a fresh round of manual tagging. A rule-computed category is the lowest-precedence source — a category set explicitly on a check through ChecksCategoriesService, and one the producing tool declared, both win over it. A typical loop is: ListCategorisationFilters to see what the workspace's checks look like, PreviewRule to check the reach of a candidate, UpsertRule to save it, then GetRecategorisationStatus to confirm the existing checks have caught up. Every workspace starts with a set of platform-provided rules covering the common cases. They are visible here, they can be superseded by a workspace rule of any priority, and they cannot be edited from a workspace. - name: synq.entities.code.v1.CodeService description: >- CodeService is a service for retrieving code associated with entities in the system. It provides functionality to access and manage code artifacts such as SQL queries, Python scripts, dbt models, and other code configurations that are part of Coalesce Quality entities. - name: synq.entities.constraints.v1.TableConstraintsService description: >- TableConstraintsService provides access to table constraint and index information. - name: synq.entities.coordinates.v1.DatabaseCoordinatesService description: >- DatabaseCoordinatesService is a service for getting database coordinates of Entities. - name: synq.entities.custom.v1.RelationshipsService description: >- RelationshipsService allow management of relationships between entities. Relationships can be created, updated, and deleted between 2 custom entities, or between a custom entity and Coalesce Quality native entity.enum There is no option to create relationships between 2 Coalesce Quality native entities (dbt model, BI dashboard, etc.). - name: synq.entities.custom.v1.ChecksRelationshipsService - name: synq.entities.custom.v1.EntitiesService description: >- custom.EntitiesService is a service for managing custom entities. Entities can represent various data platform concepts such as services, consumers, applications or data pipelines that are not natively available in Coalesce Quality. Entities are identified by a unique identifier and can be created, updated, read and deleted. - name: synq.entities.custom.v1.EntityExecutionsService - name: synq.entities.custom.v1.FeaturesService - name: synq.entities.custom.v1.GroupsService description: >- It eliminates the need to keep state on client side to remember which assets were already created and which should be deleted. The server will keep track of the current state of the group and client can always send the intended new state. The server will calculate the diff and entities that are no longer present in the group will be removed. Example: 1. group has entities A, B, C at time t1 2. client sends group with entities B, C, D at time t2 3. server will remove entity A from the system and update the current state of the group to B, C, D The service is designed to be idempotent and can be called multiple times with the same state without causing any side effects. - name: synq.entities.custom.v1.TypesService description: TypesService is a service for managing custom entity types. - name: synq.entities.entities.v1.EntitiesService description: EntitiesService is a service for retriving any entity. - name: synq.entities.executions.v1.EntityExecutionsService description: 'Deprecated: Use [synq.entities.custom.v1.EntityExecutionsService] instead' - name: synq.entities.folders.v1.FoldersService description: >- FoldersService discovers and browses the folder / containment hierarchy of the catalog: the roots data hangs from, the sub-folders under any folder, the folders a given entity lives in, and the entities contained in a folder. It is a read / navigation surface, not folder management — there are no create, move, or delete operations. Addressing: every folder has an opaque `folder_entity_id` (round-trip it verbatim) and a structured `FolderRef{root_entity_id, folders[]}` (the human-friendly form). Entities — both folder members and the ids you pass to `GetFolderOf` — are named by their opaque entity id, the same id used across the rest of the entities API. Depth footgun: membership is SHALLOW by default. `Browse` returns only the direct children of a folder, and `ListMembers` returns only the entities placed directly in the folder. Set `deep = true` (or raise `Browse.depth`) to recurse into sub-folders. - name: synq.entities.impact.v1.ImpactService - name: synq.entities.lineage.folds.v1alpha.LineageFoldsService description: >- LineageFoldsService manages the lineage folds of a workspace: rules that show many similar entities, a table or a storage path written anew on every run, as one node in lineage. See `LineageFold`. A change to a fold reaches lineage shortly after the call returns, not within it. Fold ids are UUIDs chosen by the caller, so a retried create converges on the same fold instead of making a second one. Pass the `etag` you last read on a change to guard against overwriting a concurrent edit. This API is in alpha: its shape may change without notice. - name: synq.entities.lineage.v1.LineageService description: |- LineageService allows you to fetch: * Entity level lineage from a starting point of one or more entities. * Column Level lineage from a starting point of multiple columns of a single entity. - name: synq.entities.orchestration.v1.OrchestrationService description: >- OrchestrationService tells which jobs, job steps and tasks run an entity, and which entities a job, job step or task runs, from the runs of the last 31 days. It covers Airflow tasks and DAGs, dbt Cloud job steps and Coalesce jobs. Deprecated: use synq.entities.activity.v1alpha.ActivityService. BatchGetEntityUsage answers "what runs this" for a table or a model, as its ORCHESTRATED and TRANSFORMED roles, and GetActorSummary answers "what this job runs", from its RUNS writes. - name: synq.entities.platformusers.v1alpha.PlatformUsersService description: >- PlatformUsersService reads the logins of a workspace's data platforms, as its integrations declare them and as their queries show them: how each login reads, why, how much it does and what it costs. Logins, their emails and what they read are often personal data, so every read here needs the platform users scope, which a Developer and an Admin have. - name: synq.entities.platformusers.v1alpha.ServiceAccountsService description: >- ServiceAccountsService maintains a workspace's service accounts, person links and popularity policies: which logins act for a tool, which belong to a person, and whose reads count toward an entity's popularity. Every change goes through a plan first. A typical loop is: ListPlatformUsers with unclassified_only to see the logins nothing classifies, ListServiceAccountSuggestions for the accounts their evidence points at, PlanServiceAccountChanges to see what a change set moves, then ApplyServiceAccountChanges with the plan's token. A change takes effect on the next read. Exact matchers, suggestion evidence and plans name logins, which are often personal data. A caller without the platform users scope gets them with every platform user id, login and person identity cleared, and the counts kept. A suggestion's account name and login patterns come from the logins it saw, so that caller gets those cleared too, and a suggestion named after its one login is named "Service login". - name: synq.entities.resolve.v1.IdentifierResolveService description: >- IdentifierResolveService resolves identifiers to their Coalesce Quality paths and identities. - name: synq.entities.schemas.v1.SchemaMismatchesService description: >- SchemaMismatchesService provides access to schema drift information between data platform tables and their definitions (e.g., dbt models). - name: synq.entities.schemas.v1.SchemasService description: EntitiesService is a service for retriving any entity. - name: synq.entities.semantic_models.v1alpha.OsiService description: |- OsiService converts semantic models to and from OSI, the Open Semantic Interchange format of Apache Ossie, and validates OSI documents. The service is stateless. It reads no workspace data and stores nothing, so an editor or a pipeline can call it after each change. Each response names the OSI specification version it reads and writes. The service reads and writes OSI only. To get the semantic model of an entity, use SemanticModelsService. - name: synq.entities.semantic_models.v1alpha.SemanticModelsService description: >- SemanticModelsService reads the semantic-layer model of entities: the measures, dimensions, metrics and other fields a semantic layer or BI tool declares, what each one computes, and the joins between them. The schema of an entity (synq.entities.schemas.v1) lists the same fields as flat columns. A field name here is the column name there. - name: synq.entities.sql_insights.v1.SqlInsightsService description: >- SqlInsightsService exposes analytical information about the SQL used across a workspace's entities. It answers questions such as "which SQL constructs are used in my warehouse, and by how many entities", "what SQL constructs does this specific entity use" and "which columns does building this entity join on", without requiring the caller to re-parse any SQL. - name: synq.entities.status.v1.EntityIncidentsService description: EntityIncidentsService is the service which retrieves entity status. - name: synq.entities.status.v1.EntityIssuesService description: EntityIssuesService is the service which retrieves entity issues status. - name: synq.entities.tableinfo.v1alpha.TableInfoService description: >- TableInfoService serves what a data warehouse reports about its tables and views: who owns one, when it was created, how many rows and bytes it holds, when its data last changed, and where to open it in the warehouse's own console. - name: synq.entities.typedefs.v1.TypeDefsService description: >- TypeDefsService tells you what the type values in every other endpoint mean. Responses across the API describe things by enum — an entity is an `ENTITY_TYPE_BQ_TABLE`, it belongs to `DATA_PLATFORM_TYPE_BIGQUERY`, a run is an `EXECUTION_TYPE_DBT_INVOCATION`. This service turns each of those into a name you can display and a set of facts you can act on: is this a transformation model, does it live in a warehouse, can it be monitored. Read it instead of keeping your own copy of the list. New entity types and new platforms are added as Coalesce Quality supports more tools, and a hard-coded table in your code will label them with whatever its fallback produces and miss that an existing type gained a capability. Everything here comes from the server, so you pick both up without changing your code. A typical integration calls them once at startup, keeps them in a map, and looks types up as responses arrive. It also tells you what a selection query can ask for: ListEntityTraitDefs is the vocabulary behind `traits`, which selects entities by what they are rather than by naming every type. Scoping and freshness: * ListEntityTypeDefs is per workspace, because the types you defined yourself are part of your workspace's vocabulary. It returns the built-in types and your own custom types together. * ListPlatformDefs, ListExecutionTypeDefs and ListEntityTraitDefs are the same for everyone. * The built-in half changes only when Coalesce Quality is upgraded, so caching it for the life of your process is fine. You can add or edit your own custom types at any time, so if a newly created type needs to appear promptly, cache the entity types for minutes rather than hours, or re-read after you change one. The workspace comes from your credentials; there is nothing to pass. Each list is small — hundreds of entries — so every call returns the whole set and none of them page. - name: synq.extensions.atlan.integrations.v1.AtlanIntegrationService - name: synq.extensions.atlan.provider.v1.AtlanProviderService - name: synq.extensions.atlan.workflows.v1.AtlanWorkflowService - name: synq.git.commits.v1.CommitsService - name: synq.incidents.v1.IncidentsService description: IncidentsService is a service for managing Incidents. - name: synq.ingest.airflow.v1.AirflowLogsService - name: synq.ingest.cloudwatch.v1.CloudwatchService - name: synq.ingest.dwh.v1.DwhService - name: synq.ingest.openlineage.v1.OpenlineageService - name: synq.integrations.v1.IntegrationsService description: |- IntegrationsService manages connections from Coalesce Quality to your data systems (warehouses, databases, and transformation tools). Concurrency: every integration carries an opaque `etag`. Read it from `GetIntegration` / `ListIntegrations`, then pass it back on `UpdateIntegration` / `DeleteIntegration` to ensure you modify the version you last saw. A stale etag is rejected with ABORTED (HTTP 409). Omit the etag for last-write-wins. Quota: each workspace has a limit on the number of integrations. Creating beyond the limit is rejected with RESOURCE_EXHAUSTED. Secrets: credential fields (passwords, tokens, keys) are write-only. They are masked (returned empty) on every read. On update, omit a secret to keep it, send a new value to rotate it, or send an explicit empty string to clear it (where the field is `optional`). - name: synq.issues.issues.v1.IssuesService description: IssuesService is a service for managing Issues. - name: synq.issues.v2.IssuesService description: IssuesService is a service for managing Issues. - name: synq.knowledge.v1alpha.KnowledgeService description: >- KnowledgeService reads the knowledge a team keeps about its data: knowledge pages written or imported by the team, and the descriptions people write for entities. Knowledge pages form a tree, and pages and entities are pinned to each other. Nothing here is the description an entity's own source reports, which `synq.entities.entities.v1.EntitiesService` reads. This API is in alpha: its shape may change without notice. - name: synq.monitors.automated_monitors.v1.DeploymentRulesService - name: synq.monitors.custom_monitors.v1.CustomMonitorsService - name: synq.monitors.history.v1.HistoryService - name: synq.monitors.info.v1.MonitorInfoService - name: synq.monitors.predictions.v1.MonitorPredictionsService description: Access to anomaly detection model predictions and raw metric timeseries. - name: synq.monitors.segments.v1.MonitorSegmentsService description: |- Reads and names the segments of a segmented custom monitor. A monitor configured with a segmentation expression splits the data it monitors into one time series per distinct value of that expression, and each of those is a segment. The label is what every downstream surface shows for a segment: the name of the check it produces, the search result, the alert. A segment with no label falls back to its raw value, so a monitor segmented on something encoded (an id, a code, a hashed bucket) reads as that raw value everywhere until the segment is named. - name: synq.overlays.v1.OverlaysService description: |- OverlaysService answers which organizational overlays claim an entity. An overlay is a grouping you lay over your catalog rather than something the warehouse itself knows about. Two kinds exist today: a **data product**, which groups the assets that make up something your organization delivers, and an **owner**, which names the person or team responsible for a set of assets and where alerts about them go. Each is defined by a membership rule, not by an explicit list, so what belongs to one changes as your warehouse does. "Owner" here means stewardship — who is accountable for an asset and who hears about it when something breaks. It is not the structural containment sense the word carries elsewhere in the API, where an asset can be said to own the checks and monitors declared on it. Nothing this service returns describes that relationship. This service reads that membership backwards. The defining services answer "what is in this data product"; this one answers "which data products and owners claim this table" — the question you have when you are looking at one asset and want to know who cares about it and what it feeds. Membership follows identity. Where the same table is represented more than once in your catalog — a transformation model and the warehouse table it builds — an overlay whose rule matches one of them claims the others too. So an alert routed by ownership reaches the responsible party whichever representation raised it, and you do not have to know which one a rule was written against. Two consequences worth planning around. You can ask about whichever representation you happen to hold and get the same answer, so there is no need to resolve an identity group first. And if you do ask about several members of one group in a single call, each comes back with its own entry carrying the same overlays — correct, but redundant, so ask about one member per group when you are near the request limit. Related services: - `synq.dataproducts.v2.DataproductsService` and `synq.owners.v1.OwnersService` define the overlays read here, and turn an id from a response into a name, a description and its contact channels. - `synq.entities.resolve.v1.IdentifierResolveService` turns an identifier you already hold — a warehouse table name, a dbt model — into the `entity_id` these calls take. - name: synq.owners.v1.OwnersService description: |- OwnersService manages owners and their ownerships — the "alert routing as code" surface. An owner is a named responsible party with notification channels (contacts); an ownership assigns a set of assets to an owner and configures the alerts routed to it. Owner is the resource, ownership its sub-resource: an ownership is meaningless without its owner, and deleting an owner deletes its ownerships. Ids are opaque UUIDs supplied by the caller, which makes writes idempotent (a retried create converges instead of duplicating). Mutable fields are optional on the Upsert calls: a set field is written, an omitted field is left unchanged. Pass the `etag` you last read to guard against overwriting a concurrent edit. Related: `synq.dataproducts.v2.DataproductsService` (an ownership can own a whole data product), `synq.alerts.services.v2.AlertsService` (how the configured alerts are reported), and `synq.users.v1.UsersService` (resolve the users behind `UserContact` and Slack/Teams mentions). - name: synq.platforms.v1.PlatformsService description: PlatformsService is a service for managing Platforms and Integrations. - name: synq.queries.v1.NLQueryService description: >- NLQueryService generates structured Query protos from natural language descriptions using an LLM. - name: synq.queries.v1.QueriesService description: |- QueriesService compiles and evaluates ResolverQL — the compact text query language used across Coalesce Quality to select entities — over the public API. ResolverQL is a string DSL (for example `with_type("TABLE")` or `in_folder(...)`); a structured `synq.queries.v1.Query` is its parsed, machine-readable form. This service is the bridge between the two and the read-only execution surface for both: - `TranslateResolverQl` compiles a ResolverQL expression into a structured `Query` without evaluating it — inspect it, validate it, or reuse it as a filter on another API (entity listing, folder browsing, ...). - `ResolveQuery` compiles a ResolverQL expression (or takes an already-structured `Query`), evaluates it against the catalog, and returns the matched entity ids. This is the general author -> resolve loop. - `DescribeResolverQl` returns the language itself — every function, every accepted enum value — so you author against what this deployment compiles rather than against a table baked into your client. All three authenticate and resolve your workspace from your credentials. `DescribeResolverQl` additionally needs no permission of its own, so any credential can read it; the other two read the catalog and are scoped. - name: synq.recommendations.v1.RecommendationsService description: |- RecommendationsService lists the changes Coalesce Quality recommends you make, and records what you decided about them. See `Recommendation` for what a recommendation is. Recommendations are created and removed by Coalesce Quality itself: one appears when something only you can change is found, and disappears once it no longer holds. What you can do is decide whether a recommendation stays in front of you: - Dismiss hides it until something new is found about it: an object it did not list before, or a different remediation. - Ignore hides it for good. - Restore undoes either. Decisions are kept by recommendation id, so they keep applying when a recommendation disappears and comes back. A new kind of recommendation is shown only to Coalesce Quality staff until its wording and remediation have been checked against real workspaces; everyone else reads only the released kinds (`Recommendation.released`). A recommendation about an integration is also governed by that integration's permissions: reading it needs a credential that can read integrations, and deciding about it one that can edit them. One that cannot does not see it listed. Related services: `synq.integrations.v1.IntegrationsService` manages the integrations recommendations can be about. - name: synq.savedviews.v1.SavedViewsService description: >- SavedViewsService manages saved views — named, reusable selections over your entities (and other surfaces) with display configuration, sharing and per-user pinning. A saved view is owned by the user who created it. It can be kept private, shared with the whole workspace, or granted to specific users. Reads return, for the calling user, how each view relates to them (mine / shared / granted) and what they are allowed to do with it. Workspace administrators can manage any view in the workspace. - name: synq.schedule.v1.ScheduleService description: ScheduleService provides schedule evaluation utilities. - name: synq.users.v1.UsersService paths: /api/entities/semantic-models/v1alpha/osi/render: post: tags: - synq.entities.semantic_models.v1alpha.OsiService summary: RenderOsi description: |- Render a semantic model as an OSI document. The document is always YAML. The document is always valid OSI. When the model has no value for a property that OSI requires, the document has a fallback value: a field with no expression gets its own name as the expression, and a group with no source gets its name as the source. What OSI has no property for is kept in a custom extension with the vendor name COALESCE, so ParseOsi gives back the same model. Give the whole model. A model read with field_names or without the definitions renders each measure as a plain column. To get the OSI document of an entity, call SemanticModelsService.BatchGetSemanticModels with SEMANTIC_MODEL_FORMAT_OSI. operationId: synq.entities.semantic_models.v1alpha.OsiService.RenderOsi requestBody: content: application/json: schema: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.RenderOsiRequest required: true responses: '200': description: Success content: application/json: schema: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.RenderOsiResponse components: schemas: synq.entities.semantic_models.v1alpha.RenderOsiRequest: type: object properties: semanticModel: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.SemanticModel description: The semantic model to render. title: RenderOsiRequest required: - semanticModel additionalProperties: false synq.entities.semantic_models.v1alpha.RenderOsiResponse: type: object properties: document: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.OsiDocument description: >- The OSI document, in YAML, with the OSI specification version it uses. title: RenderOsiResponse additionalProperties: false synq.entities.semantic_models.v1alpha.SemanticModel: type: object properties: declarerEntityId: type: string maxLength: 1024 description: >- Opaque id of the entity whose declaration states the model, when another entity declares it, for example the dbt project that defines a semantic model. Empty when the entity states it itself. nativeName: type: string maxLength: 1024 description: Name of the model as the declarer spells it. description: type: string maxLength: 10000 description: Description of the model. sqlPlatform: $ref: '#/components/schemas/synq.platforms.v1.DataPlatformType' description: >- The platform whose SQL the expressions are written in, when an expression does not name its own. groups: type: array items: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.FieldGroup maxItems: 10000 description: The field groups, in the declarer's order. relationships: type: array items: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.Relationship maxItems: 10000 description: The joins between the groups. aiContext: $ref: '#/components/schemas/synq.entities.semantic_models.v1alpha.AIContext' description: Context for an AI agent that reads the model. customExtensions: type: array items: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.CustomExtension maxItems: 100 description: Vendor data the declarer carries with the model. title: SemanticModel additionalProperties: false description: >- SemanticModel is the semantic-layer model of an entity: its fields in groups, what each field computes, and the joins between the groups. It is the model one declarer states for the entity, taken whole. A field name is the column name of the entity's schema, so the schema and the model join on it. The shape follows the Open Semantic Interchange (OSI) model. A group is an OSI dataset, or the part of a dataset that plays one role. synq.entities.semantic_models.v1alpha.OsiDocument: type: object properties: osiVersion: type: string maxLength: 64 description: The OSI specification version of the document. document: type: string maxLength: 10000000 description: The YAML document. title: OsiDocument additionalProperties: false description: >- OsiDocument is a semantic model as an Open Semantic Interchange document. synq.platforms.v1.DataPlatformType: type: string title: DataPlatformType enum: - DATA_PLATFORM_TYPE_UNSPECIFIED - DATA_PLATFORM_TYPE_BIGQUERY - DATA_PLATFORM_TYPE_LOOKER - DATA_PLATFORM_TYPE_DBT - DATA_PLATFORM_TYPE_DBT_CLOUD - DATA_PLATFORM_TYPE_DBT_SELF_HOSTED - DATA_PLATFORM_TYPE_SNOWFLAKE - DATA_PLATFORM_TYPE_GCP - DATA_PLATFORM_TYPE_GIT - DATA_PLATFORM_TYPE_GITHUB - DATA_PLATFORM_TYPE_REDSHIFT - DATA_PLATFORM_TYPE_TABLEAU - DATA_PLATFORM_TYPE_AIRFLOW - DATA_PLATFORM_TYPE_CLICKHOUSE - DATA_PLATFORM_TYPE_POSTGRES - DATA_PLATFORM_TYPE_MYSQL - DATA_PLATFORM_TYPE_DATABRICKS - DATA_PLATFORM_TYPE_SQLMESH - DATA_PLATFORM_TYPE_DUCKDB - DATA_PLATFORM_TYPE_TRINO - DATA_PLATFORM_TYPE_ATLAN - DATA_PLATFORM_TYPE_COALESCE - DATA_PLATFORM_TYPE_CASTORDOC - DATA_PLATFORM_TYPE_FIVETRAN - DATA_PLATFORM_TYPE_DAGSTER - DATA_PLATFORM_TYPE_AIRBYTE - DATA_PLATFORM_TYPE_STITCH - DATA_PLATFORM_TYPE_SNOWPLOW - DATA_PLATFORM_TYPE_POWERBI - DATA_PLATFORM_TYPE_THOUGHTSPOT - DATA_PLATFORM_TYPE_SIGMA - DATA_PLATFORM_TYPE_DOMO - DATA_PLATFORM_TYPE_MSSQL - DATA_PLATFORM_TYPE_ORACLE - DATA_PLATFORM_TYPE_ATHENA - DATA_PLATFORM_TYPE_FABRIC - DATA_PLATFORM_TYPE_DB2 - DATA_PLATFORM_TYPE_LOOKER_STUDIO - DATA_PLATFORM_TYPE_HEX - DATA_PLATFORM_TYPE_OMNI - DATA_PLATFORM_TYPE_METABASE - DATA_PLATFORM_TYPE_GOOGLE_SHEETS - DATA_PLATFORM_TYPE_GRAFANA - DATA_PLATFORM_TYPE_STREAMLIT - DATA_PLATFORM_TYPE_ASTRATO - DATA_PLATFORM_TYPE_SNOWFLAKE_CORTEX - DATA_PLATFORM_TYPE_SNOWFLAKE_INTELLIGENCE - DATA_PLATFORM_TYPE_CUBE - DATA_PLATFORM_TYPE_CENSUS - DATA_PLATFORM_TYPE_HIGHTOUCH - DATA_PLATFORM_TYPE_WORKATO - DATA_PLATFORM_TYPE_ESTUARY - DATA_PLATFORM_TYPE_DLT - DATA_PLATFORM_TYPE_TERRAFORM - DATA_PLATFORM_TYPE_HEVO - DATA_PLATFORM_TYPE_DATASTREAM - DATA_PLATFORM_TYPE_QLIK - DATA_PLATFORM_TYPE_SALESFORCE - DATA_PLATFORM_TYPE_SYNQ synq.entities.semantic_models.v1alpha.FieldGroup: type: object properties: name: type: string maxLength: 1024 description: >- Name of the group: the sub-container of the declarer (a Power BI table, a LookML view, an OSI dataset), or a label for the kind when the declarer has no sub-containers. kind: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.FieldGroupKind fields: type: array items: $ref: '#/components/schemas/synq.entities.semantic_models.v1alpha.Field' maxItems: 100000 description: The fields, in the declarer's order. displayName: type: string maxLength: 1024 description: >- The label the declarer shows for the group, when it differs from the name. source: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.DatasetSource description: What the group reads. description: type: string maxLength: 10000 primaryKey: type: array items: type: string maxLength: 1024 maxItems: 100 maxItems: 100 description: Names of the fields that together identify a row. uniqueKeys: type: array items: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.UniqueKey maxItems: 100 aiContext: $ref: '#/components/schemas/synq.entities.semantic_models.v1alpha.AIContext' customExtensions: type: array items: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.CustomExtension maxItems: 100 title: FieldGroup additionalProperties: false description: >- FieldGroup is a named set of fields of one kind. OSI: a dataset. One dataset can be several groups that share a name, one for each kind of field it holds. Then the dataset-level fields are set on one of them only. synq.entities.semantic_models.v1alpha.Relationship: type: object properties: name: type: string maxLength: 1024 description: Name of the join. Empty when the declarer has none. from: type: string maxLength: 1024 description: Group name of the many side. fromFields: type: array items: type: string maxLength: 1024 maxItems: 100 maxItems: 100 description: Field names of the many side, in the same order as `to_fields`. to: type: string maxLength: 1024 description: Group name of the one side, or the opaque id of another entity. toFields: type: array items: type: string maxLength: 1024 maxItems: 100 maxItems: 100 cardinality: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.Cardinality state: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.RelationshipState 'on': $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.Expression description: The join condition, when it is not a list of equal fields. joinType: $ref: '#/components/schemas/synq.entities.semantic_models.v1alpha.JoinType' nativeJoinType: type: string maxLength: 255 description: >- The declarer's spelling of the join type, when `join_type` is JOIN_TYPE_OTHER. aiContext: $ref: '#/components/schemas/synq.entities.semantic_models.v1alpha.AIContext' customExtensions: type: array items: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.CustomExtension maxItems: 100 title: Relationship additionalProperties: false description: Relationship is a join between two groups of a model. synq.entities.semantic_models.v1alpha.AIContext: type: object properties: text: type: string maxLength: 10000 description: The context as one text. The other fields are then empty. instructions: type: string maxLength: 10000 synonyms: type: array items: type: string maxLength: 1024 maxItems: 1000 maxItems: 1000 examples: type: array items: type: string maxLength: 10000 maxItems: 1000 maxItems: 1000 extraJson: type: string maxLength: 100000 description: Any other keys, as one JSON object. title: AIContext additionalProperties: false description: AIContext is context written for an AI agent that reads the model. synq.entities.semantic_models.v1alpha.CustomExtension: type: object properties: vendorName: type: string maxLength: 255 data: type: string maxLength: 100000 description: A JSON string. title: CustomExtension additionalProperties: false description: >- CustomExtension is vendor data carried with the model as the declarer gave it. synq.entities.semantic_models.v1alpha.FieldGroupKind: type: string title: FieldGroupKind enum: - FIELD_GROUP_KIND_UNSPECIFIED - FIELD_GROUP_KIND_COLUMNS - FIELD_GROUP_KIND_DIMENSIONS - FIELD_GROUP_KIND_MEASURES - FIELD_GROUP_KIND_METRICS - FIELD_GROUP_KIND_ENTITIES - FIELD_GROUP_KIND_FACTS - FIELD_GROUP_KIND_FILTERS - FIELD_GROUP_KIND_PARAMETERS description: >- FieldGroupKind is the role the fields of a group play. It is the role of each of its fields. synq.entities.semantic_models.v1alpha.Field: type: object properties: name: type: string maxLength: 1024 description: >- The address of the field: lowercased, and qualified by the sub-container when the declarer has one. It is the column name in the entity's schema, and it is unique within the model. nativeName: type: string maxLength: 1024 description: The field name as the declarer spells it, unqualified. nativeType: type: string maxLength: 1024 description: The data type as the declarer spells it. description: type: string maxLength: 10000 ordinalPosition: type: integer format: int32 description: Position of the field in the declarer's list, starting from 1. tags: type: array items: $ref: '#/components/schemas/synq.entities.v1.SchemaTag' maxItems: 100 description: Tags the declarer gives the field. definition: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.FieldDefinition description: >- What the field computes. Unset for a plain stored column, and when the request leaves the definitions out. title: Field additionalProperties: false description: Field is one field of a semantic model. synq.entities.semantic_models.v1alpha.DatasetSource: type: object oneOf: - properties: entityId: type: string title: entity_id maxLength: 1024 description: Opaque id of the entity the group reads. title: entity_id required: - entityId - properties: nativeName: type: string title: native_name maxLength: 1024 description: >- The `database.schema.table` name as the declarer spells it, when it is not resolved to an entity. title: native_name required: - nativeName - properties: query: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.Expression title: query description: A query. title: query required: - query additionalProperties: false description: DatasetSource is what a group reads. synq.entities.semantic_models.v1alpha.UniqueKey: type: object properties: fields: type: array items: type: string maxLength: 1024 maxItems: 100 maxItems: 100 description: Field names, in key order. title: UniqueKey additionalProperties: false description: UniqueKey is a set of fields that identify a row. synq.entities.semantic_models.v1alpha.Cardinality: type: string title: Cardinality enum: - CARDINALITY_UNSPECIFIED - CARDINALITY_MANY_TO_ONE - CARDINALITY_ONE_TO_ONE - CARDINALITY_ONE_TO_MANY - CARDINALITY_MANY_TO_MANY synq.entities.semantic_models.v1alpha.RelationshipState: type: string title: RelationshipState enum: - RELATIONSHIP_STATE_UNSPECIFIED - RELATIONSHIP_STATE_INACTIVE synq.entities.semantic_models.v1alpha.Expression: type: object properties: dialects: type: array items: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.DialectExpression maxItems: 100 title: Expression additionalProperties: false description: Expression is one definition, in one or more dialects. synq.entities.semantic_models.v1alpha.JoinType: type: string title: JoinType enum: - JOIN_TYPE_UNSPECIFIED - JOIN_TYPE_LEFT_OUTER - JOIN_TYPE_INNER - JOIN_TYPE_FULL_OUTER - JOIN_TYPE_CROSS - JOIN_TYPE_OTHER synq.entities.v1.SchemaTag: type: object properties: tagName: type: string maxLength: 512 minLength: 1 description: Name of the tag, in the form its kind describes. tagValue: type: string maxLength: 1000 description: Value of the tag, empty for a tag that carries none. kind: $ref: '#/components/schemas/synq.entities.v1.SchemaTagKind' description: What the data warehouse means by the tag. title: SchemaTag required: - tagName additionalProperties: false description: >- SchemaTag is a tag or label the data warehouse assigns to a table or a column. Its kind says which of the platform's tags it is, and the name is the platform's own. synq.entities.semantic_models.v1alpha.FieldDefinition: type: object properties: nativeKind: type: string maxLength: 255 description: >- The declarer's own name for the kind of object, lowercased, for example "measure", "calculated_column" or "derived_metric". For display only. expression: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.Expression description: >- What the field computes. Unset for a measure whose declarer gives only an aggregation. aggregation: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.Aggregation description: >- The aggregation the declarer applies on top of the expression. Unspecified when the aggregate is inside the expression, or when the field is not aggregated. nativeAggregation: type: string maxLength: 255 description: >- The declarer's spelling of the aggregation, when `aggregation` cannot say it exactly. timeGranularity: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.TimeGranularity description: The finest grain of a time dimension. key: $ref: '#/components/schemas/synq.entities.semantic_models.v1alpha.KeyKind' description: The key role of the field within its group. visibility: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.Visibility displayFolder: type: string maxLength: 1024 description: The folder the declarer shows the field in. format: type: string maxLength: 1024 description: The display format, as the declarer spells it. filter: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.Expression description: A row filter that is part of the definition. nonAdditiveDimensions: type: array items: type: string maxLength: 1024 maxItems: 100 maxItems: 100 description: Names of the dimensions this measure cannot be added up over. nativeKey: type: string maxLength: 255 description: >- The declarer's spelling of the key role, when `key` is KEY_KIND_OTHER. isTime: type: boolean description: >- True for a time field, false for a field the declarer says is not one. Unset when the declarer does not say. nullable: true nativeId: type: string maxLength: 1024 description: The declarer's stable id for the field, when it has one. aiContext: $ref: '#/components/schemas/synq.entities.semantic_models.v1alpha.AIContext' customExtensions: type: array items: $ref: >- #/components/schemas/synq.entities.semantic_models.v1alpha.CustomExtension maxItems: 100 displayName: type: string maxLength: 1024 description: >- The label the declarer shows its users, when it differs from the native name. title: FieldDefinition additionalProperties: false description: FieldDefinition says how a semantic-layer field is defined. synq.entities.semantic_models.v1alpha.DialectExpression: type: object properties: platform: $ref: '#/components/schemas/synq.platforms.v1.DataPlatformType' description: >- Where the expression is evaluated, which also gives its language: the SQL of a data warehouse, DAX for Power BI, LookML for Looker. Unspecified when `native_dialect` names the language, or when it is the SQL of the model's sql_platform. nativeDialect: type: string maxLength: 255 description: >- Names the language when the platform cannot, for example ANSI_SQL or MDX. expression: type: string maxLength: 10000 description: >- The expression text. A text longer than the limit is cut, and is_truncated is set. isTruncated: type: boolean description: True when the expression text was cut to fit its limit. title: DialectExpression additionalProperties: false description: DialectExpression is an expression in one dialect. synq.entities.v1.SchemaTagKind: type: string title: SchemaTagKind enum: - SCHEMA_TAG_KIND_UNSPECIFIED - SCHEMA_TAG_KIND_LABEL - SCHEMA_TAG_KIND_GOVERNED_TAG - SCHEMA_TAG_KIND_POLICY_TAG description: >- SchemaTagKind is what a data warehouse means by a tag. The platforms use the word for things that work differently, so the kind says which one a tag is rather than its name. synq.entities.semantic_models.v1alpha.Aggregation: type: string title: Aggregation enum: - AGGREGATION_UNSPECIFIED - AGGREGATION_SUM - AGGREGATION_COUNT - AGGREGATION_COUNT_DISTINCT - AGGREGATION_AVERAGE - AGGREGATION_MIN - AGGREGATION_MAX - AGGREGATION_MEDIAN - AGGREGATION_PERCENTILE - AGGREGATION_SUM_BOOLEAN - AGGREGATION_LIST - AGGREGATION_STDDEV - AGGREGATION_VARIANCE - AGGREGATION_NONE - AGGREGATION_OTHER synq.entities.semantic_models.v1alpha.TimeGranularity: type: string title: TimeGranularity enum: - TIME_GRANULARITY_UNSPECIFIED - TIME_GRANULARITY_NANOSECOND - TIME_GRANULARITY_MICROSECOND - TIME_GRANULARITY_MILLISECOND - TIME_GRANULARITY_SECOND - TIME_GRANULARITY_MINUTE - TIME_GRANULARITY_HOUR - TIME_GRANULARITY_DAY - TIME_GRANULARITY_WEEK - TIME_GRANULARITY_MONTH - TIME_GRANULARITY_QUARTER - TIME_GRANULARITY_YEAR - TIME_GRANULARITY_OTHER synq.entities.semantic_models.v1alpha.KeyKind: type: string title: KeyKind enum: - KEY_KIND_UNSPECIFIED - KEY_KIND_PRIMARY - KEY_KIND_UNIQUE - KEY_KIND_FOREIGN - KEY_KIND_NATURAL - KEY_KIND_OTHER synq.entities.semantic_models.v1alpha.Visibility: type: string title: Visibility enum: - VISIBILITY_UNSPECIFIED - VISIBILITY_HIDDEN securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.