Actions

The ballerinax/ardoq package exposes the following client:

Available clients:

Client	Purpose
`Client`	Manages Ardoq components, references, workspaces, reports, attachments, and batch operations over the Ardoq Public API (bearer-token authenticated).

Client

The Client provides access to the Ardoq Public API — components and references that model your business and IT landscape, workspaces and their type definitions, report definitions and results, attachments, and transactional batch operations.

Configuration

ConnectionConfig

Provides a set of configurations for controlling the behaviours when communicating with the Ardoq API. Passed as the first argument to the client initializer.

Field	Type	Default	Description
`auth`	`http:BearerTokenConfig`	Required	The Ardoq API token used to authenticate every request
`httpVersion`	`http:HttpVersion`	`http:HTTP_2_0`	The HTTP version understood by the client
`http1Settings`	`http:ClientHttp1Settings`		Configurations related to HTTP/1.x protocol
`http2Settings`	`http:ClientHttp2Settings`		Configurations related to HTTP/2 protocol
`timeout`	`decimal`	`30`	The maximum time to wait (in seconds) for a response before closing the connection
`forwarded`	`string`	`"disable"`	The choice of setting `forwarded`/`x-forwarded` header
`followRedirects`	`http:FollowRedirects`	Optional	Configurations associated with redirection
`poolConfig`	`http:PoolConfiguration`	Optional	Configurations associated with request pooling
`cache`	`http:CacheConfig`		HTTP caching related configurations
`compression`	`http:Compression`	`http:COMPRESSION_AUTO`	Specifies the way of handling compression (`accept-encoding`) header
`circuitBreaker`	`http:CircuitBreakerConfig`	Optional	Configurations associated with the behaviour of the Circuit Breaker
`retryConfig`	`http:RetryConfig`	Optional	Configurations associated with retrying
`cookieConfig`	`http:CookieConfig`	Optional	Configurations associated with cookies
`responseLimits`	`http:ResponseLimitConfigs`		Configurations associated with inbound response size limits
`secureSocket`	`http:ClientSecureSocket`	Optional	SSL/TLS-related options
`proxy`	`http:ProxyConfig`	Optional	Proxy server related options
`socketConfig`	`http:ClientSocketConfig`		Provides settings related to client socket configuration
`validation`	`boolean`	`true`	Enables the inbound payload validation functionality provided by the constraint package
`laxDataBinding`	`boolean`	`true`	Enables relaxed data binding on the client side, treating `nil` values and absent fields as optional

The client initializer also accepts two string parameters:

Parameter	Default	Description
`serviceUrl`	`"https://app.ardoq.com/api/v2"`	The base URL of the Ardoq API. Override it if your organization uses a dedicated Ardoq subdomain (for example, `https://your-org.ardoq.com/api/v2`)
`orgLabel`	`()`	Your Ardoq organization label. Required when using the shared `app.ardoq.com` host, since that host isn't scoped to a single organization — the connector attaches it as an `X-org` header on every request. Not needed on a dedicated subdomain

Initializing the client

import ballerinax/ardoq;

configurable string token = ?;
configurable string orgLabel = ?;

ardoq:Client ardoqClient = check new ({auth: {token: token}}, orgLabel = orgLabel);

Operations

User

getMe

Get current user and organization info.

Parameters:

Name	Type	Required	Description
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: UserInfo|error

Sample code:

UserInfo result = check ardoqClient->getMe();

Sample response:

{
  "user": { "email": "[email protected]" },
  "org": { "name": "acme-corp", "label": "Acme Corp" }
}

Workspaces

listWorkspaces

List Workspaces.

Parameters:

Name	Type	Required	Description
`queries`	`ListWorkspacesQueries`	No	Filter by `componentModel` (the Ardoq identifier of the workspace's model) or `name`
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: PaginatedWorkspaceResponse|error

Sample code:

PaginatedWorkspaceResponse result = check ardoqClient->listWorkspaces();

Sample response:

{
  "_links": {},
  "values": [
    {
      "_id": "5f3e1a2b4c1d2e3f4a5b6c01",
      "_version": 5,
      "name": "Application Portfolio",
      "description": "Tracks all business applications and their dependencies.",
      "workspaceKey": "app-portfolio",
      "startView": "dependency map",
      "views": ["dependency map", "relationships 360"]
    }
  ]
}

getWorkspace

Get a workspace.

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	An Ardoq identifier (OID)
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: Workspace|error

Sample code:

Workspace result = check ardoqClient->getWorkspace(id);

Sample response:

{
  "_id": "5f3e1a2b4c1d2e3f4a5b6c01",
  "_version": 5,
  "name": "Application Portfolio",
  "description": "Tracks all business applications and their dependencies.",
  "workspaceKey": "app-portfolio",
  "startView": "dependency map",
  "views": ["dependency map", "relationships 360"]
}

getWorkspaceContext

Workspace Context — an overview of the component types, reference types, custom fields, and tags used by the workspace's model.

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	An Ardoq identifier (OID)
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: WorkspaceContext|error

Sample code:

WorkspaceContext result = check ardoqClient->getWorkspaceContext(id);

Sample response:

{
  "rootWorkspace": "5f3e1a2b4c1d2e3f4a5b6c01",
  "componentTypes": [
    {
      "name": "Application",
      "typeId": "5f3e1a2b4c1d2e3f4a5b6c00",
      "color": "#6c5ce7",
      "customFields": ["owner", "criticality"]
    }
  ],
  "referenceTypes": [
    { "type": 2, "name": "Depends on", "customFields": [] }
  ],
  "customFields": [
    {
      "apiKey": "owner",
      "label": "Owner",
      "type": "text",
      "defaultValue": null,
      "description": "The team that owns this component.",
      "readOnly": false,
      "calculated": false
    }
  ],
  "tags": [
    { "name": "critical" }
  ]
}

Components

listComponents

List Components.

Parameters:

Name	Type	Required	Description
`queries`	`ListComponentsQueries`	No	Filter by `parent`, `name`, `rootWorkspace`, `typeId`, or `componentKey` (the "Ardoq ID" shown in the app)
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: PaginatedComponentResponse|error

Sample code:

PaginatedComponentResponse result = check ardoqClient->listComponents(queries = {rootWorkspace: workspaceId});

Sample response:

{
  "_links": {},
  "values": [
    {
      "_id": "5f3e1a2b4c1d2e3f4a5b6c7d",
      "_version": 3,
      "name": "Payment Service",
      "typeId": "5f3e1a2b4c1d2e3f4a5b6c00",
      "type": "Application",
      "rootWorkspace": "5f3e1a2b4c1d2e3f4a5b6c01",
      "description": "Handles payment processing for the checkout flow.",
      "componentKey": "payment-service",
      "color": "#6c5ce7",
      "customFields": { "owner": "platform-team" }
    }
  ]
}

getComponent

Get a component.

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	An Ardoq identifier (OID)
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: Component|error

Sample code:

Component result = check ardoqClient->getComponent(id);

Sample response:

{
  "_id": "5f3e1a2b4c1d2e3f4a5b6c7d",
  "_version": 3,
  "name": "Payment Service",
  "typeId": "5f3e1a2b4c1d2e3f4a5b6c00",
  "type": "Application",
  "rootWorkspace": "5f3e1a2b4c1d2e3f4a5b6c01",
  "description": "Handles payment processing for the checkout flow.",
  "componentKey": "payment-service",
  "color": "#6c5ce7",
  "customFields": { "owner": "platform-team" }
}

createComponent

Create a component.

Parameters:

Name	Type	Required	Description
`payload`	`CreateComponentRequest`	Yes	New component definition — `name` and `typeId` (both `anydata`, since Ardoq allows either string or numeric identifiers here) and `rootWorkspace` are required; `image`, `parent`, `shape`, `color`, `customFields`, `icon`, and `description` are optional
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: Component|error

Sample code:

Component result = check ardoqClient->createComponent({
    name: "Payment Service",
    rootWorkspace: workspaceId,
    typeId: applicationTypeId
});

Sample response:

{
  "_id": "5f3e1a2b4c1d2e3f4a5b6c7d",
  "_version": 1,
  "name": "Payment Service",
  "typeId": "5f3e1a2b4c1d2e3f4a5b6c00",
  "rootWorkspace": "5f3e1a2b4c1d2e3f4a5b6c01",
  "customFields": {}
}

updateComponent

Update a component.

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	An Ardoq identifier (OID)
`payload`	`UpdateComponentRequest`	Yes	Fields to update — `image`, `parent`, `color`, `shape`, `customFields`, `name`, `icon`, `description` are all optional
`queries`	`UpdateComponentQueries`	Yes	`ifVersionMatch` (required) — the expected version, either a positive integer or `"latest"`, used for concurrency control
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: Component|error

Sample code:

Component result = check ardoqClient->updateComponent(id, {description: "Handles payment processing and refunds."}, queries = {ifVersionMatch: "latest"});

Sample response:

{
  "_id": "5f3e1a2b4c1d2e3f4a5b6c7d",
  "_version": 4,
  "name": "Payment Service",
  "typeId": "5f3e1a2b4c1d2e3f4a5b6c00",
  "rootWorkspace": "5f3e1a2b4c1d2e3f4a5b6c01",
  "description": "Handles payment processing and refunds.",
  "customFields": { "owner": "platform-team" }
}

deleteComponent

Delete a component.

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	An Ardoq identifier (OID)
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: error?

Sample code:

error? result = check ardoqClient->deleteComponent(id);

References

listReferences

List References.

Parameters:

Name	Type	Required	Description
`queries`	`ListReferencesQueries`	No	Filter by `displayText`, `targetWorkspace`, `rootWorkspace`, `source`, `type`, or `target`
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: PaginatedReferenceResponse|error

Sample code:

PaginatedReferenceResponse result = check ardoqClient->listReferences(queries = {rootWorkspace: workspaceId});

Sample response:

{
  "_links": {},
  "values": [
    {
      "_id": "5f3e1a2b4c1d2e3f4a5b6c10",
      "_version": 1,
      "source": "5f3e1a2b4c1d2e3f4a5b6c7d",
      "target": "5f3e1a2b4c1d2e3f4a5b6c7e",
      "type": 2,
      "displayText": "depends on",
      "rootWorkspace": "5f3e1a2b4c1d2e3f4a5b6c01",
      "customFields": {}
    }
  ]
}

getReference

Get a reference.

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	An Ardoq identifier (OID)
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: Reference|error

Sample code:

Reference result = check ardoqClient->getReference(id);

Sample response:

{
  "_id": "5f3e1a2b4c1d2e3f4a5b6c10",
  "_version": 1,
  "source": "5f3e1a2b4c1d2e3f4a5b6c7d",
  "target": "5f3e1a2b4c1d2e3f4a5b6c7e",
  "type": 2,
  "displayText": "depends on",
  "rootWorkspace": "5f3e1a2b4c1d2e3f4a5b6c01",
  "customFields": {}
}

createReference

Create a Reference.

Parameters:

Name	Type	Required	Description
`payload`	`CreateReferenceRequest`	Yes	New reference definition — `source`, `target`, and `type` (the reference type ID defined by the root workspace's model) are required; `displayText`, `customFields`, and `description` are optional
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: Reference|error

Sample code:

Reference result = check ardoqClient->createReference({
    'source: paymentServiceId,
    target: ledgerServiceId,
    'type: dependsOnTypeId
});

Sample response:

{
  "_id": "5f3e1a2b4c1d2e3f4a5b6c10",
  "_version": 1,
  "source": "5f3e1a2b4c1d2e3f4a5b6c7d",
  "target": "5f3e1a2b4c1d2e3f4a5b6c7e",
  "type": 2,
  "customFields": {}
}

updateReference

Update a Reference.

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	An Ardoq identifier (OID)
`payload`	`UpdateReferenceRequest`	Yes	Fields to update — `displayText`, `customFields`, `description`, `source`, `target` are all optional
`queries`	`UpdateReferenceQueries`	Yes	`ifVersionMatch` (required) — the expected version, either a positive integer or `"latest"`, used for concurrency control
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: Reference|error

Sample code:

Reference result = check ardoqClient->updateReference(id, {displayText: "depends on (critical path)"}, queries = {ifVersionMatch: "latest"});

Sample response:

{
  "_id": "5f3e1a2b4c1d2e3f4a5b6c10",
  "_version": 2,
  "source": "5f3e1a2b4c1d2e3f4a5b6c7d",
  "target": "5f3e1a2b4c1d2e3f4a5b6c7e",
  "type": 2,
  "displayText": "depends on (critical path)",
  "customFields": {}
}

deleteReference

Delete a reference.

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	An Ardoq identifier (OID)
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: error?

Sample code:

error? result = check ardoqClient->deleteReference(id);

Reports

listReports

List Report definitions.

Parameters:

Name	Type	Required	Description
`queries`	`ListReportsQueries`	No	Filter by `name`
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: PaginatedReportResponse|error

Sample code:

PaginatedReportResponse result = check ardoqClient->listReports(queries = {name: "Application Criticality Report"});

Sample response:

{
  "_links": {},
  "values": [
    {
      "_id": "5f3e1a2b4c1d2e3f4a5b6c20",
      "_version": 2,
      "name": "Application Criticality Report",
      "description": "Lists all applications with their criticality rating.",
      "datasource": "graphSearch",
      "columns": [
        { "label": "Name", "key": "name" },
        { "label": "Criticality", "key": "cf_criticality" }
      ]
    }
  ]
}

getReport

Report definition.

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	An Ardoq identifier (OID)
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: ReportOverview|error

Sample code:

ReportOverview result = check ardoqClient->getReport(id);

Sample response:

{
  "_id": "5f3e1a2b4c1d2e3f4a5b6c20",
  "_version": 2,
  "name": "Application Criticality Report",
  "description": "Lists all applications with their criticality rating.",
  "datasource": "graphSearch",
  "columns": [
    { "label": "Name", "key": "name" },
    { "label": "Criticality", "key": "cf_criticality" }
  ]
}

runReportObjects

Run Report (Objects).

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	An Ardoq identifier (OID)
`queries`	`RunReportObjectsQueries`	No	`keyFormat` — `"label"` (default) or `"key"`, controlling whether result object keys are column labels or API keys
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: PaginatedReportObjectResponse|error

Sample code:

PaginatedReportObjectResponse result = check ardoqClient->runReportObjects(id);

Sample response:

{
  "_links": {},
  "values": [
    { "name": "Payment Service", "cf_criticality": "High" },
    { "name": "Ledger Service", "cf_criticality": "Medium" }
  ]
}

runReportTabular

Run Report (Tabular).

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	An Ardoq identifier (OID)
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: PaginatedReportTabularResponse|error

Sample code:

PaginatedReportTabularResponse result = check ardoqClient->runReportTabular(id);

Sample response:

{
  "_links": {},
  "_meta": {
    "name": "Application Criticality Report",
    "columns": [
      { "label": "Name", "key": "name" },
      { "label": "Criticality", "key": "cf_criticality" }
    ]
  },
  "values": [
    ["Payment Service", "High"],
    ["Ledger Service", "Medium"]
  ]
}

Attachments

listAttachments

List attachments.

Parameters:

Name	Type	Required	Description
`queries`	`ListAttachmentsQueries`	No	Filter by `filename` or `folder` (the `id` of the folder the attachment is in)
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: PaginatedAttachmentResponse|error

Sample code:

PaginatedAttachmentResponse result = check ardoqClient->listAttachments();

Sample response:

{
  "_links": {},
  "values": [
    {
      "_id": "5f3e1a2b4c1d2e3f4a5b6c30",
      "_version": 1,
      "filename": "architecture-diagram.png",
      "folder": null,
      "resource-type": "workspace",
      "resource-id": "5f3e1a2b4c1d2e3f4a5b6c01"
    }
  ]
}

getAttachment

Get an attachment.

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	An Ardoq identifier (OID)
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: Attachment|error

Sample code:

Attachment result = check ardoqClient->getAttachment(id);

Sample response:

{
  "_id": "5f3e1a2b4c1d2e3f4a5b6c30",
  "_version": 1,
  "filename": "architecture-diagram.png",
  "folder": null,
  "resource-type": "workspace",
  "resource-id": "5f3e1a2b4c1d2e3f4a5b6c01"
}

Batch Operations

executeBatch

Execute a batch request — create, update, or delete many components and references in a single transactional call. Use the aliases block to reference components/references being created in the same request before they have a real Ardoq identifier.

Parameters:

Name	Type	Required	Description
`payload`	`BatchRequest`	Yes	`components` and/or `references` operations (each with `create`, `upsert`, `update`, `delete` lists), an optional `aliases` block for cross-referencing entities created in the same batch, and optional `options` (e.g. `respondWithEntities` to include full entity bodies in the response)
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: BatchResponse|error

Sample code:

BatchResponse result = check ardoqClient->executeBatch({
    components: {
        create: [
            {batchId: "new-payment-service", body: {name: "Payment Service", rootWorkspace: workspaceId, typeId: applicationTypeId}},
            {batchId: "new-ledger-service", body: {name: "Ledger Service", rootWorkspace: workspaceId, typeId: applicationTypeId}}
        ]
    },
    references: {
        create: [
            {batchId: "dependency-1", body: {'source: "new-payment-service", target: "new-ledger-service", 'type: dependsOnTypeId}}
        ]
    }
});

Sample response:

{
  "components": {
    "created": [
      { "batchId": "new-payment-service", "id": "5f3e1a2b4c1d2e3f4a5b6c7d" },
      { "batchId": "new-ledger-service", "id": "5f3e1a2b4c1d2e3f4a5b6c7e" }
    ]
  },
  "references": {
    "created": [
      { "batchId": "dependency-1", "id": "5f3e1a2b4c1d2e3f4a5b6c10" }
    ]
  }
}

expandBatch

Expand Batch — resolves aliases and batch-local references in a batch request body without executing it, useful for previewing what a subsequent executeBatch call would do.

Parameters:

Name	Type	Required	Description
`payload`	`BatchRequest`	Yes	Same shape as the `executeBatch` payload
`headers`	`map<string\|string[]>`	No	Headers to be sent with the request

Returns: BatchRequest|error

Sample code:

BatchRequest result = check ardoqClient->expandBatch({
    components: {
        create: [
            {batchId: "new-payment-service", body: {name: "Payment Service", rootWorkspace: workspaceId, typeId: applicationTypeId}}
        ]
    }
});

Sample response:

{
  "components": {
    "create": [
      {
        "batchId": "new-payment-service",
        "body": {
          "name": "Payment Service",
          "rootWorkspace": "5f3e1a2b4c1d2e3f4a5b6c01",
          "typeId": "5f3e1a2b4c1d2e3f4a5b6c00"
        }
      }
    ]
  }
}

Client​

Configuration​

ConnectionConfig​

Initializing the client​

Operations​

User​

Workspaces​

Components​

References​

Reports​

Attachments​

Batch Operations​

Client

Configuration

ConnectionConfig

Initializing the client

Operations

User

Workspaces

Components

References

Reports

Attachments

Batch Operations