Entrypoints Client Methods#

This page lists all relevant methods for Dioptra Entrypoints that are available via the Python Client.

Contents

Requirements #

Install Dioptra - an installation and deployment of Dioptra must be available
Set Up the Python Client - the Python client must be configured and initialized

Swap selections in snapshot queries #

The snapshot config and dynamicGlobalParameters GET endpoints accept swap selections using the OpenAPI 3 deepObject wire representation (style: deepObject, explode: true):

?swaps[method]=attack%3Av2&swaps[secondary]=attack%2Cv3

This selects attack:v2 for method and attack,v3 for secondary. Swap names and aliases are preserved exactly. Each swaps[name] parameter must occur only once; repeated keys, including repeated identical values, return HTTP 400. Omit swap parameters when there are no selections. The former swaps=name:alias,name2:alias2 format is no longer accepted.

The Python client’s get_config(swap_parameters=...) and get_task_graph_global_params(swaps=...) methods accept dictionaries and handle this serialization automatically. Pass the original names and aliases without pre-encoding them. For direct HTTP calls, let the URL library encode both keys and values:

params = {
    "swaps[method]": "attack:v2",
    "swaps[secondary]": "attack,v3",
}

The current Swagger 2 documentation describes this bracketed format in the parameter description; Swagger 2 cannot express OpenAPI 3 deepObject metadata.

Entrypoints - CRUD methods #

After importing and initializing the client, these methods for creating, reading, updating, and deleting (CRUD) entrypoints can be executed via client.entrypoints.METHOD_NAME(). Create Entrypoint ~~~~~~~~~~~~~~~~~

EntrypointsCollectionClient.create(group_id: int, name: str, task_graph: str, artifact_graph: str | None = None, description: str | None = None, parameters: list[dict[str, Any]] | None = None, artifact_parameters: list[dict[str, Any]] | None = None, queues: list[int] | None = None, plugins: list[int] | None = None, artifact_plugins: list[int] | None = None, validate_only: bool = False) → dioptra.client.entrypoints.T[source]#
Creates a entrypoint.

Parameters

group_id – The id of the group that will own the entrypoint.

name – The name of the new entrypoint.

task_graph – The task graph for the new entrypoint as a YAML-formatted string.

artifact_graph – The artifact graph for the new entrypoint as a YAML-formatted string. Optional, defaults to None. A None value indicates there are no produced artifacts that need to be stored.

description – The description of the new entrypoint. Optional, defaults to None.

parameters – The list of parameters for the new entrypoint. Optional, defaults to None.

artifact_parameters – The list of artifact parameters for the new entrypoint. Optional, defaults to None.

queues – A list of queue ids to associate with the new entrypoint. Optional, defaults to None.

plugins – A list of plugin ids to associate with the new entrypoint. Optional, defaults to None.

artifact_plugins – A list of artifact plugin ids to associate with the new entrypoint. Optional, defaults to None.

validate_only – If True, run all save-time checks, then roll back without committing changes. The response omits generated IDs/timestamps. If False (the default), validate and save the entrypoint.
Example

Create an entrypoint called “hello_world” with artifact input parameters and artifact output graph.
entrypoint = client.entrypoints.create(
    group_id=GROUP_ID,
    name="hello_world",
    task_graph=TASK_GRAPH_YAML_STR,
    artifact_graph=ARTIFACT_TASK_GRAPH_YAML_STR,
    description="An entrypoint to run hello world task",
    parameters=[
        {
            "name": "greeting",
            "defaultValue": "Hello",
            "parameterType": "string",
        },
        {
            "name": "name",
            "defaultValue": "World",
            "parameterType": "string",
        },
    ],
    artifact_parameters=[
        {
            "name": "artifact_name",
            "outputParams": [
                {"name": "value", "parameterType": STRING_PARAM_TYPE_ID}
            ],
        }
    ],
    queues=[QUEUE_ID_1],
    plugins=[PLUGIN_ID_1],
    artifact_plugins=[PLUGIN_ID_2],
)
Returns

The response from the Dioptra API.

Get Entrypoints #

EntrypointsCollectionClient.get(group_id: int | None = None, index: int = 0, page_length: int = 10, sort_by: str | None = None, descending: bool | None = None, search: str | None = None, show_deleted: bool | None = None) → dioptra.client.entrypoints.T[source]#

Get a list of entrypoints.

Parameters

group_id – The group id the entrypoints belong to. If None, return entrypoints from all groups that the user has access to. Optional, defaults to None.

index – The paging index. Optional, defaults to 0.

page_length – The maximum number of entrypoints to return in the paged response. Optional, defaults to 10.

sort_by – The field to use to sort the returned list. Optional, defaults to None.

descending – Sort the returned list in descending order. Optional, defaults to None.

search – Search for entrypoints using the Dioptra API’s query language. Optional, defaults to None.

Returns

The response from the Dioptra API.

Get One Entrypoint #

EntrypointsCollectionClient.get_by_id(entrypoint_id: str | int) → dioptra.client.entrypoints.T[source]#

Get the entrypoint matching the provided id.

Parameters

entrypoint_id – The entrypoint id, an integer.

Returns

The response from the Dioptra API.

Modify Entrypoint #

EntrypointsCollectionClient.modify_by_id(entrypoint_id: str | int, name: str, task_graph: str, artifact_graph: str | None, description: str | None, parameters: list[dict[str, Any]] | None, artifact_parameters: list[dict[str, Any]] | None, queues: list[int] | None, plugin_snapshot_ids: list[int], artifact_plugin_snapshot_ids: list[int], validate_only: bool = False) → dioptra.client.entrypoints.T[source]#

Modify the entrypoint matching the provided id.

Parameters

entrypoint_id – The entrypoint id, an integer.

name – The new name of the entrypoint.

task_graph – The new task graph for the entrypoint as a YAML-formatted string.

artifact_graph – The artifact graph for the new entrypoint as a YAML-formatted string. To remove the artifact graph, pass None.

description – The new description of the entrypoint. To remove the description, pass None.

parameters – The new list of parameters for the entrypoint. To remove all parameters, pass None.

artifact_parameters – The list of artifact parameters for the new entrypoint. To remove all artifact parameters, pass None.

queues – The new list of queue ids to associate with the entrypoint. To remove all associated queues, pass None.

plugin_snapshot_ids – The complete desired task-plugin snapshot list. Retain the currently bound snapshot or select latest independently for each plugin. New associations require latest; omitted plugins are removed. Pass an empty list to remove all task plugins, subject to graph validation.

artifact_plugin_snapshot_ids – The complete desired artifact-plugin snapshot list, with the same eligibility and removal rules for this role.

validate_only – If True, run all save-time checks, then roll back without committing changes. The response omits generated IDs/timestamps. If False (the default), validate and save the entrypoint.

Returns

The response from the Dioptra API.

Delete Entrypoint #

EntrypointsCollectionClient.delete_by_id(entrypoint_id: str | int) → dioptra.client.entrypoints.T[source]#

Delete the entrypoint matching the provided id.

Parameters

entrypoint_id – The entrypoint id, an integer.

Returns

The response from the Dioptra API.

Entrypoints - Validation Dry Runs #

Use the ordinary entrypoint create or update interface with validateOnly=true to validate a proposed entrypoint without saving it:

POST /api/v1/entrypoints/?validateOnly=true
PUT /api/v1/entrypoints/{id}?validateOnly=true

Send the same request body as for an ordinary create or update. In the Python client, pass validate_only=True to create() or modify_by_id(). For example:

response = client.entrypoints.create(
    group_id=GROUP_ID,
    name="hello_world",
    task_graph=TASK_GRAPH_YAML_STR,
    plugins=PLUGIN_IDS,
    parameters=PARAMETERS,
    validate_only=True,
)

Dry runs perform the same permission, association, name, and full graph validation checks as saving, then roll back without committing changes. Database flushes may occur within the transaction, but resources, snapshots, and associations are not saved. Errors have the same status and details as the corresponding save. Successful requests return the proposed entrypoint representation, omitting the new snapshot ID, snapshot timestamp, and modification timestamp. The latestSnapshot and deleted fields are retained. Creation dry runs additionally omit the generated resource ID and creation timestamp. Update dry runs retain the existing resource ID and original creation timestamp.

Omitting validateOnly or setting it to false (validate_only=False in the Python client) performs full validation and saves the entrypoint.

Lightweight lint reports #

For inexpensive editor feedback, use POST /api/v1/entrypoints:lint or POST /api/v1/entrypoints/{id}:lint with the corresponding create or update content fields. The colon is a literal part of the URL. Item lint uses the saved plugin associations and accepts entrypoint content without PUT’s snapshot lists. These endpoints perform schema, task-reference, and swap checks without full rendered-graph validation. Changes are rolled back on both success and failure.

report = client.entrypoints.lint({
    "group": GROUP_ID,
    "name": "hello_world",
    "taskGraph": TASK_GRAPH_YAML_STR,
    "plugins": PLUGIN_IDS,
}).json()

report = client.entrypoints.lint_by_id(ENTRYPOINT_ID, {
    "name": "hello_world",
    "taskGraph": TASK_GRAPH_YAML_STR,
}).json()

A completed check returns HTTP 200 with a report such as:

{"valid": false, "issues": [{"path": "graph", "message": "Unknown task"}]}

Malformed requests, authorization failures, missing resources, and operational failures return normal API errors. A successful lint report does not replace a full dry run or save-time validation.

Entrypoint Plugins - Methods #

These methods exist within the class EntrypointPluginsSubCollectionClient, and are accessed via the plugins property of the Entrypoint Client (which points to EntrypointPluginsSubCollectionClient).

Example - Attach Plugins to Entrypoint

Attach Plugins to an Entrypoint

client.entrypoints.plugins.create(entrypoint_id=1, plugin_ids=[2,3])

Add Plugin to Entrypoint #

EntrypointPluginsSubCollectionClient.create(entrypoint_id: str | int, plugin_ids: list[int]) → dioptra.client.entrypoints.T[source]#

Adds one or more plugins to the entrypoint.

If a plugin id matches an plugin that is already attached to the entrypoint, then the entrypoint will update the plugin to the latest version.

Parameters

entrypoint_id – The entrypoint id, an integer.

plugin_ids – A list of plugin ids that will be registered to the entrypoint.

Returns

The response from the Dioptra API.

Get Plugins for Entrypoint #

EntrypointPluginsSubCollectionClient.get(entrypoint_id: int | str) → dioptra.client.entrypoints.T[source]#

Get a list of plugins added to the entrypoint.

Parameters

entrypoint_id – The entrypoint id, an integer.

Returns

The response from the Dioptra API.

Get One Plugin by ID #

EntrypointPluginsSubCollectionClient.get_by_id(entrypoint_id: str | int, plugin_id: str | int) → dioptra.client.entrypoints.T[source]#

Get the entrypoint plugin matching the provided id.

Parameters

entrypoint_id – The entrypoint id, an integer.

plugin_id – The id for the plugin that will be removed.

Returns

The response from the Dioptra API.

Delete One Plugin by ID #

EntrypointPluginsSubCollectionClient.delete_by_id(entrypoint_id: str | int, plugin_id: str | int) → dioptra.client.entrypoints.T[source]#

Remove a plugin from the entrypoint.

Parameters

entrypoint_id – The entrypoint id, an integer.

plugin_id – The id for the plugin that will be removed.

Returns

The response from the Dioptra API.

Entrypoint Artifact Plugins - Methods #

These methods exist within the class EntrypointArtifactPluginsSubCollectionClient, and are accessed via the artifact_plugins property of the Entrypoint Client.

Example - Attach Artifact Plugins to Entrypoint

client.entrypoints.artifact_plugins.create(entrypoint_id=1, artifact_plugin_ids=[5])

Add Artifact Plugin to Entrypoint #

EntrypointArtifactPluginsSubCollectionClient.create(entrypoint_id: str | int, artifact_plugin_ids: list[int]) → dioptra.client.entrypoints.T[source]#

Adds one or more artifact plugins to the entrypoint.

If a artifact plugin id matches an artifact plugin that is already attached to the entrypoint, then the entrypoint will update the artifact plugin to the latest version.

Parameters

entrypoint_id – The entrypoint id, an integer.

artifact_plugin_ids – A list of artifact plugin ids that will be registered to the entrypoint.

Returns

The response from the Dioptra API.

Get Artifact Plugins for Entrypoint #

EntrypointArtifactPluginsSubCollectionClient.get(entrypoint_id: int | str) → dioptra.client.entrypoints.T[source]#

Get a list of artifact plugins added to the entrypoint.

Parameters

entrypoint_id – The entrypoint id, an integer.

Returns

The response from the Dioptra API.

Get One Artifact Plugin by ID #

EntrypointArtifactPluginsSubCollectionClient.get_by_id(entrypoint_id: str | int, artifact_plugin_id: str | int) → dioptra.client.entrypoints.T[source]#

Get the entrypoint plugin matching the provided id.

Parameters

entrypoint_id – The entrypoint id, an integer.

artifact_plugin_id – The id for the plugin that will be retrieved.

Returns

The response from the Dioptra API.

Delete One Artifact Plugin by ID #

EntrypointArtifactPluginsSubCollectionClient.delete_by_id(entrypoint_id: str | int, artifact_plugin_id: str | int) → dioptra.client.entrypoints.T[source]#

Remove an artifact plugin from the entrypoint.

Parameters

entrypoint_id – The entrypoint id, an integer.

artifact_plugin_id – The id for the artifact plugin that will be removed.

Returns

The response from the Dioptra API.

Entrypoint Queues - Methods #

These methods exist within the class EntrypointQueuesSubCollectionClient, and are accessed via the queues property of the Entrypoint Client.

Example - Attach Queues to Entrypoint

client.entrypoints.queues.create(entrypoint_id=1, queue_ids=[10])

Add Queue to Entrypoint #

EntrypointQueuesSubCollectionClient.create(entrypoint_id: str | int, queue_ids: list[int]) → dioptra.client.entrypoints.T[source]#

Adds one or more queues to the entrypoint.

Parameters

entrypoint_id – The entrypoint id, an integer.

queue_ids – A list of queue ids that will be registered to the entrypoint.

Returns

The response from the Dioptra API.

Get Queues for Entrypoint #

EntrypointQueuesSubCollectionClient.get(entrypoint_id: int | str) → dioptra.client.entrypoints.T[source]#

Get a list of queues added to the entrypoint.

Parameters

entrypoint_id – The entrypoint id, an integer.

Returns

The response from the Dioptra API.

Replace Attached Queues #

EntrypointQueuesSubCollectionClient.modify_by_id(entrypoint_id: str | int, queue_ids: list[int]) → dioptra.client.entrypoints.T[source]#

Replaces the entrypoint’s full list of queues.

If an empty list is provided, then all queues will be removed from the entrypoint.

Parameters

entrypoint_id – The entrypoint id, an integer.

queue_ids – A list of queue ids that will replace the current list of entrypoint queues.

Returns

The response from the Dioptra API.

Delete All Attached Queues #

EntrypointQueuesSubCollectionClient.delete(entrypoint_id: str | int) → dioptra.client.entrypoints.T[source]#

Remove all queues from the entrypoint.

Parameters

entrypoint_id – The entrypoint id, an integer.

Returns

The response from the Dioptra API.

Delete One Queue by ID #

EntrypointQueuesSubCollectionClient.delete_by_id(entrypoint_id: str | int, queue_id: str | int) → dioptra.client.entrypoints.T[source]#

Remove a queue from the entrypoint.

Parameters

entrypoint_id – The entrypoint id, an integer.

queue_id – The id for the queue that will be removed.

Returns

The response from the Dioptra API.

Tags Attached to Entrypoint - Methods #

Methods belonging to the TagsSubCollectionClient are accessed via the tags property of the Entrypoint Client (which points to TagsSubCollectionClient).

Example - Get tags for an Entrypoint

client.entrypoints.tags.get(1)

See available methods for the TagsSubCollectionClient: